211 lines
9.1 KiB
Markdown
211 lines
9.1 KiB
Markdown
<!-- file: deltas/0.2.4/pre.001.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.2.4-pre.001` — audit Blocks/Economics, compliance cible et sizing
|
||
|
||
## Base requise
|
||
|
||
Release stable attendue :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
nouvelle dépendance NON
|
||
solana-rpc-client/client NON
|
||
base64/bs58 NON
|
||
```
|
||
|
||
## Prévision de travail
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md
|
||
deltas/0.2.4/pre.001.md
|
||
```
|
||
|
||
## Fichiers modifiés
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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 :
|
||
|
||
```bash
|
||
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` :
|
||
|
||
```text
|
||
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.
|