v0.2.4-pre.005

2026-08-18 21:03:00 +02:00
parent 561b6678ed
commit d3cc7c93f0
8 changed files with 544 additions and 12 deletions
--- a/deltas/0.2.4/pre.005.md
+++ b/deltas/0.2.4/pre.005.md
@@ -0,0 +1,355 @@
+<!-- file: deltas/0.2.4/pre.005.md -->
+<!-- version: 1 -->
+
+# Delta `0.2.4-pre.005` — `getBlockProduction`
+
+## Base requise
+
+Livraison précédente :
+
+```text
+0.2.4-pre.004
+workspace.package.version = "0.2.4-pre.4"
+```
+
+Les validations locales fournies pour cette base sont propres :
+
+```text
+cargo fmt --all                         -> terminé
+cargo check --workspace                 -> terminé sans warning
+cargo clippy --workspace --all-targets  -> terminé sans warning
+cargo test -p ksp-onchain-transport-lib -> 208 unit tests OK
+                                           22 public API tests OK
+                                           17 release-completeness tests OK
+                                           1 smoke Devnet ignoré comme prévu
+                                           0 échec
+```
+
+## Objectif
+
+Implémenter exactement la tranche dédiée prévue par le plan `0.2.4` :
+
+```text
+getBlockProduction
+```
+
+Cette méthode est déjà enregistrée dans la partition :
+
+```text
+V0_2_4 / Blocks / Read / RetrySafe
+```
+
+Le registre central n'est donc pas modifié.
+
+Après cette tranche, neuf des dix wrappers Blocks de `0.2.4` sont matérialisés. Il reste volontairement :
+
+```text
+pre.006  getBlock
+```
+
+Les cinq méthodes Economics restent hors scope jusqu'aux tranches `pre.007` et `pre.008`.
+
+## Réaudit RPC de la tranche
+
+Le contrat stable a été recroisé avec Agave `v4.2.1` avant implémentation.
+
+`RpcBlockProductionConfig` expose exactement :
+
+```text
+identity: Option<String>
+range: Option<{firstSlot, lastSlot?}>
+commitment: Option<CommitmentConfig>
+```
+
+Le résultat est contextualisé :
+
+```text
+RpcResponse<RpcBlockProduction>
+```
+
+avec :
+
+```text
+context
+value.byIdentity
+value.range.firstSlot
+value.range.lastSlot
+```
+
+`byIdentity` associe chaque validator identity aux comptes :
+
+```text
+(leader slots, blocks produced)
+```
+
+Le runtime Agave rejette `lastSlot < firstSlot`. KSP effectue donc le même contrôle déterministe avant I/O.
+
+Aucune restriction locale `confirmed/finalized` n'est appliquée au commitment de `getBlockProduction` : le `CommitmentConfig` général du runtime est préservé, y compris `processed`.
+
+Aucun nouvel overload, champ ou type de résultat n'a été identifié ; le plan `011` reste donc inchangé en version 3.
+
+## Version Cargo
+
+Nouvelle prerelease technique :
+
+```text
+0.2.4-pre.4 -> 0.2.4-pre.5
+```
+
+Aucune dépendance ni feature Cargo n'est ajoutée ou modifiée.
+
+## Wrapper typed `getBlockProduction`
+
+Signature publique :
+
+```text
+HttpTransportPool::get_block_production(
+    role,
+    Option<&SolanaBlockProductionConfig>,
+) -> Result<SolanaRpcResponse<SolanaBlockProduction>>
+```
+
+La configuration publique acquise en `pre.002` est réutilisée sans duplication :
+
+```text
+SolanaBlockProductionConfig
+SolanaBlockProductionRange
+```
+
+Exemple complet :
+
+```json
+[
+  {
+    "commitment":"finalized",
+    "identity":"11111111111111111111111111111111",
+    "range":{"firstSlot":430000000,"lastSlot":430000099}
+  }
+]
+```
+
+Une plage ouverte conserve l'absence de `lastSlot` :
+
+```json
+[
+  {
+    "commitment":"processed",
+    "range":{"firstSlot":430000000}
+  }
+]
+```
+
+Un `Some(SolanaBlockProductionConfig::default())` est canoniquement omis et produit :
+
+```json
+[]
+```
+
+Il n'existe ici aucun overload positional dont la distinction dépendrait d'un objet vide ; l'omission est donc équivalente au config runtime par défaut.
+
+## Validation déterministe avant I/O
+
+Lorsque les deux bornes sont explicites :
+
+```text
+lastSlot >= firstSlot -> valide
+lastSlot <  firstSlot -> rejet avant I/O
+```
+
+L'erreur KSP utilise le domaine partagé :
+
+```text
+ERROR_CODE_INVALID_RPC_PARAMETERS
+```
+
+avec contexte non secret :
+
+```text
+rpc_method
+first_slot
+last_slot
+```
+
+Aucune autre validation économique ou de commitment n'est inventée.
+
+## Résultat contextualisé
+
+Le wrapper préserve le `SolanaRpcResponse<T>` commun :
+
+```text
+context.slot
+context.apiVersion?
+value.byIdentity
+value.range
+```
+
+Les clés de `byIdentity` sont décodées en `Pubkey` KSP. Une clé wire invalide ferme le décodage avec `ERROR_CODE_INVALID_RESPONSE` sans recopier la valeur fautive dans le diagnostic.
+
+Les couples :
+
+```text
+(leader slots, blocks produced)
+```
+
+sont conservés exactement ; Transport ne recalcule pas les statistiques et n'interprète pas leur économie.
+
+## Discipline `#[cfg(test)]`
+
+La règle introduite par `pre.002-fix.001` reste appliquée.
+
+Éléments devenus runtime dans cette tranche parce qu'ils ont désormais un consommateur réel :
+
+```text
+SolanaBlockProductionRange::to_json_value
+SolanaBlockProductionConfig::is_empty
+SolanaBlockProductionConfig::to_json_value
+SolanaBlockProduction::decode_wire
+WireBlockProductionRange
+WireBlockProduction
+WireBlockProductionRpcResponse
+```
+
+Éléments déjà runtime des tranches précédentes :
+
+```text
+SolanaBlockCommitment::decode_wire
+WireBlockCommitment
+SolanaPerformanceSample::decode_wire
+WirePerformanceSample
+```
+
+Restent test-only jusqu'à `pre.006` :
+
+```text
+SolanaGetBlockConfig::{is_empty,to_json_value}
+SolanaBlockReward::decode_wire
+SolanaBlockTransaction::decode_wire
+SolanaConfirmedBlock::decode_wire
+helpers privés transaction/reward de bloc
+WireBlockReward
+WireBlockTransaction
+WireConfirmedBlock
+```
+
+Tous les helpers/wires Economics restent également test-only jusqu'à leurs prereleases dédiées.
+
+Aucun `#[allow(dead_code)]` n'est introduit.
+
+## Fixtures HTTP ajoutées
+
+```text
+crates/ksp-onchain-transport-lib/fixtures/http/get_block_production.success.json
+crates/ksp-onchain-transport-lib/fixtures/http/get_block_production.invalid_identity.json
+```
+
+Elles couvrent :
+
+- contexte `slot + apiVersion` ;
+- `byIdentity` typé ;
+- plage effective ;
+- erreur fermée sur identity wire invalide.
+
+## Tests ajoutés
+
+Quatre unit tests HTTP sont ajoutés :
+
+```text
+typed_get_block_production_serializes_full_config_and_decodes_contextual_result
+typed_get_block_production_omits_empty_config_and_supports_open_range_with_processed_commitment
+typed_get_block_production_rejects_reversed_range_before_io
+typed_get_block_production_rejects_invalid_wire_identity_without_echoing_value
+```
+
+Une canarie public API vérifie que le wrapper reste disponible depuis la racine de crate :
+
+```text
+public_v0_2_4_pre_005_block_production_wrapper_is_available_from_crate_root
+```
+
+Une canarie release-completeness vérifie le descriptor :
+
+```text
+release_v0_2_4_pre_005_block_production_subset_is_exact_and_retry_safe
+```
+
+Compteurs attendus après validation locale :
+
+```text
+212 unit tests
+23 public API tests
+18 release-completeness tests
+1 smoke Devnet ignoré
+```
+
+## Fichiers modifiés
+
+```text
+Cargo.toml
+crates/ksp-onchain-transport-lib/src/rpc_blocks.rs
+crates/ksp-onchain-transport-lib/unit_tests/rpc_blocks.rs
+crates/ksp-onchain-transport-lib/tests/public_api.rs
+crates/ksp-onchain-transport-lib/tests/release_completeness.rs
+```
+
+## Fichiers ajoutés
+
+```text
+crates/ksp-onchain-transport-lib/fixtures/http/get_block_production.success.json
+crates/ksp-onchain-transport-lib/fixtures/http/get_block_production.invalid_identity.json
+deltas/0.2.4/pre.005.md
+```
+
+Aucun fichier n'est supprimé.
+
+## Validation attendue
+
+À exécuter après application de l'overlay :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-onchain-transport-lib
+```
+
+Les critères de fermeture sont :
+
+```text
+aucun warning introduit
+212 unit tests OK
+23 public API tests OK
+18 release-completeness tests OK
+smoke Devnet ignoré comme prévu
+0 échec
+```
+
+Le sandbox de préparation ne possède pas le toolchain Cargo/Rust ; aucune compilation locale n'est revendiquée par ce delta.
+
+## Commit attendu
+
+Après validation locale :
+
+```text
+v0.2.4-pre.005
+```
+
+## Suite
+
+La prerelease suivante reste :
+
+```text
+0.2.4-pre.006
+```
+
+Scope prévu :
+
+```text
+réaudit SIMD-0298 / SIMD-0307
+getBlock moderne
+bare encoding legacy
+transactionDetails
+wire bloc riche
+SIMD-0118 numRewardPartitions
+SIMD-0291 commissionBps
+canary version transaction numérique non zéro / SIMD-0385
+```