v0.2.4-pre.001-fix.001

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

@@ -0,0 +1,191 @@
+<!-- file: deltas/0.2.4/pre.001-fix.001.md -->
+<!-- version: 1 -->
+
+# Delta `0.2.4-pre.001-fix.001` — audit SIMD Transport et correction des matrices du plan
+
+## Base requise
+
+Ce fix s'applique après :
+
+```text
+0.2.4-pre.001
+workspace.package.version = "0.2.4-pre.1"
+```
+
+Le delta historique `deltas/0.2.4/pre.001.md` reste inchangé.
+
+## Motif du fix
+
+Deux corrections documentaires sont nécessaires avant `pre.002` :
+
+1. les matrices Blocks/Economics du plan utilisaient des caractères `|` à l'intérieur de cellules Markdown, notamment dans des unions telles que `object | null`; certains renderers les interprètent comme des séparateurs de colonnes même lorsqu'ils sont placés dans du code inline ;
+2. l'apparition de `commissionBps` liée à SIMD-0291 impose de vérifier systématiquement si d'autres SIMDs actuels ou proches de la baseline stable affectent la surface HTTP couverte par `KSP-TRANSPORT-007`.
+
+Ce fix ne modifie aucun wrapper ni source Rust. Il complète le plan avant l'implémentation afin que les modifications nécessaires soient réalisées dans les prereleases fonctionnelles prévues.
+
+## Audit SIMD `KSP-TRANSPORT-007`
+
+Le critère retenu est le wire réellement supporté par la baseline Solana/Agave stable, pas le seul statut administratif d'un SIMD. Un SIMD encore en `Review` peut donc être pertinent si Agave stable expose déjà un champ de compatibilité ; inversement, un champ proposé mais absent d'Agave stable n'est pas inventé par KSP.
+
+### SIMD à prendre en compte dans `0.2.4`
+
+**SIMD-0118 — Partitioned Epoch Rewards Distribution**
+
+- statut actuel : `Activated` ;
+- impact HTTP direct : `getBlock.numRewardPartitions` ;
+- Agave `v4.2.1` expose `UiConfirmedBlock.num_reward_partitions: Option<u64>` ;
+- le futur DTO bloc KSP doit préserver la présence/omission du champ, sans synthétiser `0` ;
+- le plan retient `SolanaWireField<u64>` ou une représentation wire équivalente et des fixtures `present`/`omitted`.
+
+**SIMD-0291 — Commission Rate in Basis Points**
+
+- statut actuel du document SIMD : `Review` ;
+- Agave stable `v4.2.1` expose néanmoins déjà les champs RPC de compatibilité en basis points ;
+- `getVoteAccounts.inflationRewardsCommissionBps` est déjà implémenté et testé par la surface `0.2.2` : aucune remédiation des 37 wrappers acquis ;
+- `getBlock.rewards[].commissionBps` doit être conservé dans un reward wire de bloc dédié ;
+- `getInflationReward[].commissionBps` doit être conservé dans le DTO d'inflation reward ;
+- `commission` reste nullable et `commissionBps` reste optionnel/omis ; KSP ne dérive pas l'un depuis l'autre ;
+- `getTransaction.meta` de `0.2.3` est déjà lossless en `serde_json::Value`, donc les rewards imbriqués ne perdent pas cette extension.
+
+### SIMDs déjà couverts ou sans nouveau wire immédiat
+
+**SIMD-0185 — Vote Account v4** est `Accepted`. Les évolutions des account parsers restent compatibles avec `SolanaParsedAccountData.parsed: serde_json::Value`. Le DTO stable `RpcVoteAccountInfo` d'Agave `v4.2.1` n'expose pas les collector fields de Vote Account v4 ; KSP ne les ajoute pas spéculativement à `SolanaVoteAccountInfo`.
+
+**SIMD-0186 — Loaded Transaction Data Size Specification** est `Accepted`. `simulateTransaction.loadedAccountsDataSize` est déjà préservé dans `0.2.3` via `SolanaWireField<u32>` avec couverture de l'omission. Transport restitue cette valeur runtime et ne la recalcule pas.
+
+**SIMD-0385 — Transaction V1 Format** est en `Review`. Le contrat KSP actuel est déjà future-compatible parce que `SolanaTransactionVersion::Number(u8)` n'est pas limité à la version `0` et les payloads JSON restent lossless. Le plan ajoute toutefois une canary avec une version numérique non nulle et impose la même propriété au wire `getBlock`.
+
+**SIMD-0096 — Reward full priority fee to validator** est `Activated`, mais modifie la distribution économique sans modifier la forme HTTP consommée par Transport. Aucun calcul de distribution ne doit être réimplémenté côté KSP.
+
+**SIMD-0550 — Double Disinflation Rate** est en `Review` et annonce explicitement une évolution des valeurs retournées par `getInflationRate` et `getInflationGovernor` sans changement d'API. Les DTOs KSP restent des valeurs runtime et Transport ne réimplémente aucune formule d'inflation.
+
+### Watchlist obligatoire
+
+**SIMD-0180 — Vote Account Address Keyed Leader Schedule** est en `Review`. Il demande que les endpoints RPC existants de leader schedule continuent à retourner l'identité validator pour compatibilité et prévoit de nouveaux endpoints vote-account-keyed. Le wrapper `getLeaderSchedule` existant ne change donc pas ; le réaudit final de l'inventaire doit en revanche détecter si de nouveaux endpoints sont devenus officiels.
+
+**SIMD-0307 — Add Block Footer** est en `Review` et propose une option `footer` ainsi que de nouveaux champs dans `getBlock`. **SIMD-0298 — Add `bank_hash` to block footer** est encore au statut `Idea` et prévoit d'étendre ce footer avec `bank_hash`. Ces éléments sont absents de la baseline stable Agave `v4.2.1`. Ils ne sont donc pas ajoutés maintenant, mais le plan impose un réaudit conjoint avant `getBlock` et à la compliance finale. S'ils deviennent stables pendant `0.2.4`, `KSP-TRANSPORT-007` imposera config, wire et fixtures pour la totalité des champs livrés.
+
+**SIMD-0490 — Upgrade BPF Stake Program to v5.0.0** est en `Review` et prévoit une évolution du minimum de délégation. `getStakeMinimumDelegation` doit restituer la valeur runtime contextualisée sans coder en dur `1 lamport`, `1 SOL` ou une autre valeur. Réaudit prévu avant la tranche Economics concernée et à la clôture.
+
+**SIMD-0553 — Base Inclusion and Resource-based Fee** est en `Draft`. Il modifie la sémantique des totals de fee pour `getFeeForMessage`, `simulateTransaction` et `getTransaction.meta.fee` mais n'impose actuellement pas de nouveau JSON wire. Les wrappers acquis restent pass-through/lossless ; la compliance finale réaudite ce point si le schéma stable évolue.
+
+**SIMD-0123 — Block Revenue Sharing** reste en `Review`. Il peut modifier à terme la provenance/sémantique des rewards sans ajouter aujourd'hui un champ HTTP stable dans `v4.2.1`. KSP ne crée donc aucune taxonomie économique spéculative dans le reward wire.
+
+## Modifications désormais prévues par le plan
+
+Les prereleases fonctionnelles devront notamment prévoir :
+
+```text
+getBlock
+  confirmed block dédié
+  numRewardPartitions préservé via SolanaWireField<u64> ou équivalent (SIMD-0118)
+  reward de bloc dédié
+  commission nullable
+  commissionBps optionnel/omis (SIMD-0291)
+  transaction version Number(u8) non limitée à 0 (canary SIMD-0385)
+  réaudit conjoint SIMD-0298/0307 avant implémentation finale du contrat
+
+getInflationReward
+  reward d'inflation distinct du reward de bloc
+  commission nullable
+  commissionBps optionnel/omis (SIMD-0291)
+
+getStakeMinimumDelegation
+  valeur runtime contextualisée
+  aucun minimum local codé en dur
+  réaudit SIMD-0490
+
+compliance pre.009
+  réaudit SIMD HTTP au minimum 0180 / 0298 / 0307 / 0385 / 0490 / 0550 / 0553
+  réaudit de l'inventaire officiel pour détecter de nouveaux endpoints
+  vérification qu'aucune évolution devenue stable pendant la session n'est omise
+```
+
+Aucune nouvelle dépendance n'est requise par ces décisions.
+
+## Correction des matrices Markdown
+
+Les deux matrices du plan ont été réécrites avec les mêmes quatre largeurs de colonnes afin d'être alignées dans la source Markdown.
+
+Les unions textuelles qui contenaient un pipe interne ont été remplacées par `ou`, notamment :
+
+```text
+object ou null
+array<u64> ou null
+i64 ou null
+commission: u8 ou null
+```
+
+Le contrôle statique du fichier exige désormais exactement cinq caractères `|` par ligne de tableau : un délimiteur initial, trois séparateurs de colonnes et un délimiteur final. Il n'existe plus de pipe de données à l'intérieur d'une cellule.
+
+## Version Cargo
+
+Ce fix est exclusivement documentaire. Conformément à la règle de versioning des fixes documentaires, le signal technique reste :
+
+```text
+workspace.package.version = "0.2.4-pre.1"
+```
+
+Aucune modification de `Cargo.toml` n'est effectuée.
+
+## Fichier modifié
+
+```text
+docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md
+```
+
+Le header documentaire du plan passe de `version: 1` à `version: 2`.
+
+## Fichier ajouté
+
+```text
+deltas/0.2.4/pre.001-fix.001.md
+```
+
+## Fichiers volontairement inchangés
+
+```text
+Cargo.toml
+CHANGELOG.md
+ROADMAP.md
+deltas/0.2.4/pre.001.md
+crates/ksp-onchain-transport-lib/src/**
+crates/ksp-onchain-transport-lib/unit_tests/**
+crates/ksp-onchain-transport-lib/tests/**
+```
+
+Les structures/fonctions Rust requises par l'audit sont planifiées pour les tranches fonctionnelles de `0.2.4`; elles ne sont pas introduites artificiellement dans ce fix documentaire d'ouverture.
+
+## Validations exécutées
+
+- réaudit primaire du repository SIMD courant et de la baseline Agave stable `v4.2.1` ;
+- confirmation de SIMD-0118 `Activated` et de son lien avec `numRewardPartitions` ;
+- confirmation dans Agave `v4.2.1` du champ `UiConfirmedBlock.num_reward_partitions` ;
+- confirmation dans Agave `v4.2.1` de `Reward.commission_bps` et `RpcInflationReward.commission_bps` ;
+- confirmation que `RpcVoteAccountInfo.inflation_rewards_commission_bps` est déjà couvert dans KSP `0.2.2` ;
+- confirmation que `SolanaTransactionVersion::Number(u8)` et les payloads transaction/meta lossless de `0.2.3` n'imposent pas de remédiation SIMD-0385 ;
+- confirmation que SIMD-0180 est encore `Review`, que les RPC leader schedule existants doivent conserver l'identité validator, et que les futurs endpoints vote-account-keyed relèvent d'une évolution d'inventaire ;
+- confirmation que SIMD-0186 est `Accepted` et que `loadedAccountsDataSize` est déjà couvert losslessly dans `simulateTransaction` ;
+- confirmation que SIMD-0298 est encore `Idea`, dépend du block footer de SIMD-0307 et ne justifie aucun champ `bankHash` spéculatif dans la baseline actuelle ;
+- confirmation que SIMD-0307 est encore `Review` et que ses champs footer sont absents des types stables Agave `v4.2.1` ;
+- confirmation que SIMD-0490 est encore `Review` et que le wrapper KSP ne doit pas figer une valeur de minimum delegation ;
+- confirmation que SIMD-0550 est encore `Review` et déclare une évolution de valeurs inflation sans changement d'API ;
+- confirmation que SIMD-0553 est encore `Draft` et n'impose pas actuellement de nouvelle forme JSON ;
+- contrôle des deux matrices : quatre colonnes et exactement cinq délimiteurs `|` par ligne ;
+- contrôle que le delta `pre.001.md` historique reste inchangé.
+
+## Validations Cargo
+
+Aucune source Rust, configuration runtime, dépendance ou version Cargo n'est modifiée par ce fix. Les validations Cargo de `pre.001` restent celles à effectuer par l'opérateur avant commit ; ce fix n'en revendique aucune nouvelle.
+
+## Commit attendu
+
+Après application et validation documentaire :
+
+```text
+v0.2.4-pre.001-fix.001
+```
+
+## Suite
+
+`0.2.4-pre.002` peut démarrer les primitives/configs/results communs en intégrant dès leur conception les exigences SIMD-0118 et SIMD-0291 fixées ci-dessus, avec les watchpoints SIMD explicitement reportés aux tranches concernées.