khadhroony-solana-project/deltas/0.2.4/pre.001.md

Delta 0.2.4-pre.001 — audit Blocks/Economics, compliance cible et sizing

Base requise

Release stable attendue :

v0.2.3

L'archive KSP fournie porte workspace.package.version = "0.2.3". Elle ne contient pas .git; le tag v0.2.3 n'est donc pas revérifiable localement depuis le zip.

Objectif

Ouvrir 0.2.4 sans implémentation fonctionnelle lourde : relire les contrats KSP, réauditer la documentation Solana actuelle et la génération Agave stable, confirmer les 10 méthodes Blocks + 5 Economics, cadrer les overloads/legacy/DTOs/wires et contraintes KSP-TRANSPORT-007, puis trancher le gate de sizing avant les modifications Rust.

Version Cargo

Conformément à VER-ID-009, la prerelease non-fix synchronise le signal technique :

0.2.3 -> 0.2.4-pre.1

Aucune source Rust, dépendance Cargo ou configuration runtime n'est modifiée dans cette tranche.

Résultats principaux

• l'index HTTP Solana courant conserve 52 méthodes courantes ;
• les catégories Blocks et Economics restent exactement 10 + 5 méthodes, sans changement de partition ;
• la navigation Deprecated conserve les 14 méthodes historiques déjà enregistrées par KSP ;
• les 15 descriptors HttpRpcCoverageRelease::V0_2_4 présents dans v0.2.3 correspondent exactement à l'inventaire officiel actuel et restent Read / RetrySafe ;
• getBlock reste StableWithDeprecatedLegacy parce que son second paramètre accepte toujours un bare encoding legacy en plus de l'objet de config moderne ;
• la documentation Solana actuelle lie encore ses sources RPC à Agave v3.1.8; elle doit donc être cross-auditée contre la génération stable réellement courante ;
• au 2026-08-18, la baseline runtime retenue est Agave v4.2.1 dans la branche stable 4.2.x; v4.3.0-beta.0 reste une prerelease ;
• getBlock accepte la config moderne complète commitment/encoding/transactionDetails/maxSupportedTransactionVersion/rewards, conserve la forme bare encoding et retourne object|null ;
• les transactions de bloc partagent les primitives SolanaEncodedTransaction, SolanaTransactionVersion et SolanaWireField<T> avec 0.2.3, mais ne doivent pas réutiliser SolanaConfirmedTransaction tel quel car ce DTO contient des champs top-level propres à getTransaction ;
• getBlocks conserve les overloads [start], [start,end], [start,config], [start,end,config]; une différence end-start > 500_000 est invalide, tandis que end < start produit un tableau vide ;
• getBlocksWithLimit conserve limit <= 500_000; limit = 0 est valide ;
• getRecentPerformanceSamples conserve 720 comme défaut et maximum ;
• getBlockProduction conserve identity, range.firstSlot, range.lastSlot?, commitment, une réponse contextualisée et l'invariant déterministe lastSlot >= firstSlot ;
• getInflationReward conserve l'ordre/cardinalité et les null positionnels ; Agave v4.2.1 expose en plus de commission le champ optionnel commissionBps: u16, absent de la page publique actuelle, qui doit être préservé par KSP ;
• aucune limite sémantique fixe d'adresses getInflationReward n'a été établie par les sources courantes : KSP n'en invente pas une à partir de la limite générale de taille de requête ;
• getSupply conserve excludeNonCirculatingAccountsList et le résultat contextualisé {total,circulating,nonCirculating,nonCirculatingAccounts} ;
• aucune nouvelle dépendance n'est nécessaire pour cette release.

Gate de sizing

Question obligatoire :

Les 15 wrappers Blocks/Economics, leurs DTOs/wires, les overloads/legacy,
les tests, la compliance 52+14 et la documentation peuvent-ils être
clôturés proprement dans cette release/session ?

Réponse :

OUI.

Aucun split de release n'est nécessaire. La complexité sera contrôlée en isolant getBlock, getBlockProduction, getInflationReward et la compliance finale dans des tranches dédiées. Une prerelease supplémentaire sera créée si une tranche dépasse le budget effectif d'environ 15–20 minutes ; aucune méthode ne sera reportée silencieusement hors de 0.2.4.

Décisions de conception

Réutilisation wire

Réutiliser directement :

SolanaCommitment
SolanaCommitmentConfig
SolanaContextConfig
SolanaRpcContext
SolanaRpcResponse<T>
SolanaTransactionEncoding
SolanaEncodedTransaction
SolanaTransactionVersion
SolanaWireField<T>

Créer des DTOs Blocks/Economics seulement lorsque le contrat wire est réellement distinct.

getBlock

Le résultat de bloc aura un type dédié. Les entrées transactions[] composent les primitives Transaction existantes mais ne réutilisent pas SolanaConfirmedTransaction tel quel. Les champs conditionnels issus de transactionDetails/rewards doivent conserver leurs omissions et null significatifs.

Contraintes déterministes avant I/O

Retenues :

getBlock                    commitment >= confirmed
getBlocks                   commitment >= confirmed
getBlocks                   end-start <= 500_000 lorsque end >= start
getBlocksWithLimit          commitment >= confirmed
getBlocksWithLimit          limit <= 500_000
getRecentPerformanceSamples limit <= 720
getBlockProduction          lastSlot >= firstSlot lorsque les deux sont présents

Ne pas transformer en validations locales les erreurs dépendant de l'état du ledger/runtime.

Dépendances

nouvelle dépendance         NON
solana-rpc-client/client    NON
base64/bs58                 NON

Prévision de travail

pre.001  audit officiel + Agave stable + matrice + wires + contraintes + sizing
pre.002  primitives/configs/results Blocks/Economics partagés + fixtures communes
pre.003  5 Blocks simples
pre.004  getBlocks + getBlocksWithLimit + getRecentPerformanceSamples
pre.005  getBlockProduction
pre.006  getBlock moderne + legacy + transactionDetails + wire riche
pre.007  4 Economics simples
pre.008  getInflationReward + commissionBps + null positionnels
pre.009  compliance finale 52/52 + 14/14 + docs + smokes + graphes + prompt 0.2.5
rel.001  publication stricte

Le plan détaillé est docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md.

Fichiers ajoutés

docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md
deltas/0.2.4/pre.001.md

Fichiers modifiés

Cargo.toml
ROADMAP.md
docs/000-README.md
docs/plans/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md

Fichiers supprimés

Aucun.

Fichiers volontairement inchangés

CHANGELOG.md
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/**
crates/ksp-onchain-transport-lib/unit_tests/**
crates/ksp-onchain-transport-lib/tests/**
deltas/0.2.1/**
deltas/0.2.2/**
deltas/0.2.3/**

Le changelog reste synchronisé à la phase documentaire finale conformément à VER-SESSION-005. Les deltas historiques ne sont jamais réécrits.

Validations exécutées

• relecture des sources internes obligatoires du prompt 0.2.4 ;
• inspection de l'archive stable KSP fournie et de la surface Transport v0.2.3 ;
• confirmation locale de workspace.package.version = 0.2.3 avant ouverture ;
• confirmation locale du registry 52 current / 14 historical et de la partition 4 / 22 / 11 / 15 ;
• confirmation locale que les 15 descriptors V0_2_4 sont exactement les 10 Blocks + 5 Economics attendues et sont Read / RetrySafe ;
• inspection des wires partagés rpc_common et rpc_transactions ainsi que des canaries de release ;
• consultation de l'index HTTP Solana officiel courant, du JSON Structures Reference et des 15 pages Blocks/Economics ;
• consultation de la navigation Deprecated officielle courante ;
• confirmation que les liens source de la documentation publique pointent encore vers Agave v3.1.8 ;
• cross-audit primaire d'Agave v4.2.1 : release stable, rpc/src/rpc.rs, rpc-client-types/src/config.rs et response.rs ;
• confirmation des overloads getBlocks, limites 500_000/720, contrainte de range getBlockProduction et extension commissionBps de getInflationReward ;
• contrôle qu'aucune nouvelle dépendance n'est requise par le plan.

Validations non exécutées

Le sandbox courant ne fournit pas le binaire cargo; les validations Cargo ne peuvent donc pas être exécutées ici et doivent être rejouées par l'opérateur avant commit :

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-onchain-transport-lib

Aucun cargo tree n'est nécessaire dans pre.001 puisque les dépendances/features ne changent pas. Les graphes complets restent obligatoires à la clôture pre.009.

L'archive fournie ne contient pas .git; le commit attendu après application et validations suit VER-GIT-001 :

v0.2.4-pre.001

Questions ouvertes

Aucune question bloquante pour pre.002.

Suite

0.2.4-pre.002 : introduire les primitives/configs/results Blocks/Economics partagés et les fixtures déterministes communes, sans encore concentrer toute la logique de getBlock dans la même tranche.