181 lines
7.8 KiB
Markdown
181 lines
7.8 KiB
Markdown
<!-- file: deltas/0.2.2/pre.001.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.2.2-pre.001` — réaudit HTTP Accounts/Tokens/Cluster, DTOs et sizing
|
||
|
||
## Base requise
|
||
|
||
Release stable attendue :
|
||
|
||
```text
|
||
v0.2.1
|
||
```
|
||
|
||
L'archive KSP fournie porte `workspace.package.version = "0.2.1"`. Elle ne contient pas `.git`; le tag `v0.2.1` n'est donc pas revérifiable
|
||
localement depuis le zip.
|
||
|
||
## Objectif
|
||
|
||
Exécuter la première tranche obligatoire de `0.2.2` sans implémentation fonctionnelle lourde : relire les contrats KSP, réauditer la surface
|
||
HTTP Solana officielle actuelle, confirmer la matrice des 22 méthodes Accounts/Tokens/Cluster, cadrer les DTOs wire, évaluer les dépendances et
|
||
trancher le gate de sizing.
|
||
|
||
## Version Cargo
|
||
|
||
Conformément à `VER-ID-009`, la prerelease non-fix synchronise le signal technique :
|
||
|
||
```text
|
||
0.2.1 -> 0.2.2-pre.1
|
||
```
|
||
|
||
Aucune source Rust, dépendance Cargo ou configuration runtime n'est modifiée dans cette tranche.
|
||
|
||
## Résultats principaux
|
||
|
||
- index HTTP Solana courant réaudité : **52 méthodes** ;
|
||
- navigation Deprecated officielle : **14 méthodes historiques**, inchangées ;
|
||
- familles de la release : Accounts `6 = 1 acquis + 5 ciblés`, Tokens `5 = 5 ciblés`, Cluster `15 = 3 acquis + 12 ciblés` ;
|
||
- aucune méthode ajoutée/supprimée/déplacée détectée depuis l'audit `0.2.1` du 2026-08-17 ;
|
||
- les 22 méthodes ciblées restent des méthodes courantes non marquées Deprecated/Unstable et les descriptors KSP restent `Read + RetrySafe` ;
|
||
- `getMultipleAccounts` conserve la limite documentée de 100 adresses ;
|
||
- `getSlotLeaders` conserve la limite documentée `1..=5000` ;
|
||
- `getLargestAccounts` et `getProgramAccounts` documentent toujours `sortResults` ;
|
||
- `getProgramAccounts` conserve sa réponse bare par défaut et contextualisée avec `withContext=true` ;
|
||
- la source primaire Agave confirme trois filtres Program Accounts (`dataSize`, `memcmp`, `tokenAccountState`), 4 filtres max et 128 octets décodés max pour `memcmp` ;
|
||
- le wire Account requiert une union pour `data`, y compris le fallback `jsonParsed -> [base64]`, et `space` reste nullable ;
|
||
- `TokenAmount.uiAmount` reste nullable ;
|
||
- `getHighestSnapshotSlot` conserve `incremental: null` et la source officielle Agave confirme une erreur `NoSnapshot` en absence de snapshot ;
|
||
- `getLeaderSchedule` conserve son overload slot/config particulier ;
|
||
- `getVoteAccounts` conserve `current/delinquent` et les epoch credits triples; la source Agave courante borne cet historique RPC à 5 entrées par validator.
|
||
|
||
## Gate de sizing
|
||
|
||
Question obligatoire :
|
||
|
||
```text
|
||
Les 22 wrappers typés + DTOs partagés + tests + documentation peuvent-ils être clôturés proprement dans cette session ?
|
||
```
|
||
|
||
Réponse :
|
||
|
||
```text
|
||
OUI.
|
||
```
|
||
|
||
Aucun split de release n'est nécessaire. Le plan conserve `0.2.2` à 22 méthodes et répartit le travail sur DTOs communs, Accounts, Tokens,
|
||
Cluster simple, Cluster schedule/slot/vote puis clôture. Si une tranche réelle dépasse le budget KSP, elle sera scindée par une prerelease
|
||
supplémentaire sans déplacer de méthode hors `0.2.2`.
|
||
|
||
## Décisions prises
|
||
|
||
- conserver exactement la partition `4 / 22 / 11 / 15` de `0.2.1`–`0.2.4` ;
|
||
- ne pas reconstruire un transport par famille ; tous les wrappers passent par descriptor + `execute_standard_rpc` ;
|
||
- mutualiser `SolanaCommitment` et `SolanaRpcContext` sans casser les réexports `0.2.1` ;
|
||
- représenter Account data comme une forme wire discriminée, sans décodage Program/SPL ;
|
||
- conserver `jsonParsed.parsed` comme `serde_json::Value` dans Transport ;
|
||
- utiliser `ksp_core_lib::Pubkey` dans les DTOs publics, avec wire structs privés puis conversion explicite ;
|
||
- représenter le selector Token comme une union exclusive `mint` / `programId` ;
|
||
- représenter le résultat `getProgramAccounts` comme bare ou contextualisé selon `withContext` ;
|
||
- conserver les endpoints de `getClusterNodes` comme chaînes wire optionnelles au contrat public ;
|
||
- conserver les `null` documentés (`Account`, `space`, `uiAmount`, `transactionCount`, snapshot incremental, leader schedule) ;
|
||
- ne pas modifier Config : le contrat `std.transport` existant suffit ;
|
||
- ne pas ajouter `base64`, `bs58`, SPL, `solana-client` ou SDK RPC haut niveau à `pre.001`; les formes encodées `memcmp` peuvent rester des chaînes wire tant qu’aucun décodage local n’est requis.
|
||
|
||
## Prévision de travail
|
||
|
||
```text
|
||
pre.001 audit officiel + matrice + DTOs + dépendances + sizing
|
||
pre.002 primitives/configs/results partagés + fixtures de base
|
||
pre.003 5 Accounts + tests
|
||
pre.004 5 Tokens + tests
|
||
pre.005 Cluster simple (7 méthodes) + tests
|
||
pre.006 Cluster schedule/slot/vote (5 méthodes) + tests
|
||
pre.007 canaries + smoke opt-in si utile + docs + prompt 0.2.3 + préparation stable
|
||
```
|
||
|
||
Une prerelease supplémentaire reste autorisée si le budget réel d'une tranche l'exige.
|
||
|
||
## Fichiers ajoutés
|
||
|
||
```text
|
||
docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md
|
||
deltas/0.2.2/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
|
||
docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
|
||
docs/validation/003-V0_2_1_ONCHAIN_HTTP.md
|
||
crates/ksp-onchain-transport-lib/src/**
|
||
crates/ksp-onchain-transport-lib/unit_tests/**
|
||
crates/ksp-onchain-transport-lib/tests/**
|
||
crates/ksp-config-lib/src/transport.rs
|
||
config/std.transport.json
|
||
config/schemas/std.transport.schema.json
|
||
```
|
||
|
||
Les deltas `0.2.1` restent historiques et ne sont pas réécrits.
|
||
|
||
## Validations exécutées
|
||
|
||
- relecture des sources KSP obligatoires du prompt `0.2.2` ;
|
||
- inspection de l'archive stable KSP fournie et de la foundation Transport `0.2.1` ;
|
||
- confirmation locale que le registry assigne déjà exactement les 22 méthodes ciblées à `HttpRpcCoverageRelease::V0_2_2` ;
|
||
- confirmation locale que ces 22 descriptors sont `Stable / Supported / Stable`, `Read`, `RetrySafe` ;
|
||
- consultation de l'index HTTP Solana officiel courant et des 22 pages de méthodes ciblées ;
|
||
- consultation de la navigation Deprecated officielle courante ;
|
||
- consultation de `Solana RPC JSON Structures` pour Account data et TokenAmount ;
|
||
- consultation des sources Agave `v3.1.8` liées par les pages officielles pour les ambiguïtés Account, filters/memcmp, cardinalités RPC, largest accounts, snapshot, leader schedule,
|
||
cluster node et vote accounts ;
|
||
- contrôle documentaire de la matrice `52 current / 14 historical / 4+22+11+15` ;
|
||
- contrôle de l'absence de nouvelle dépendance ou de besoin Config dans le design de `pre.001`.
|
||
|
||
## Validations non exécutées
|
||
|
||
Le sandbox courant ne fournit pas le binaire `cargo` (`command -v cargo` ne retourne aucun chemin). Les validations Cargo suivantes n'ont donc pas
|
||
été exécutées ici et doivent être rejouées sur le checkout de développement 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 cette tranche car aucune dépendance ni feature n'a changé. Les quatre vues `cargo tree` du prompt restent
|
||
obligatoires dès qu'une prerelease change une dépendance/feature et à la clôture.
|
||
|
||
L'archive KSP fournie ne contient pas `.git`; le commit attendu après application et validations suit `VER-GIT-001` :
|
||
|
||
```text
|
||
v0.2.2-pre.001
|
||
```
|
||
|
||
## Questions ouvertes
|
||
|
||
Aucune question bloquante pour `pre.002`.
|
||
|
||
Les détails exacts de nommage Rust des DTOs restent ajustables pendant leur implémentation, mais les invariants wire et frontières fixés par le
|
||
plan `009` ne doivent pas être relâchés pour simplifier artificiellement les wrappers.
|
||
|
||
## Suite
|
||
|
||
`0.2.2-pre.002` : introduire les primitives/configs/results partagés, mutualiser Context/Commitment, fixer les conversions wire et installer les
|
||
fixtures déterministes communes avant les wrappers Accounts.
|