From 9059a2dc45063365d41d5de7636f6fd4b8e34d0f Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Tue, 18 Aug 2026 06:41:41 +0200 Subject: [PATCH] v0.2.2-pre.001 --- Cargo.toml | 4 +- ROADMAP.md | 4 +- deltas/0.2.2/pre.001.md | 180 +++++++ docs/000-README.md | 7 +- docs/plans/000-README.md | 3 +- docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md | 4 +- ...0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md | 497 ++++++++++++++++++ 7 files changed, 690 insertions(+), 9 deletions(-) create mode 100644 deltas/0.2.2/pre.001.md create mode 100644 docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md diff --git a/Cargo.toml b/Cargo.toml index 8428549..dde83bb 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 109 +# version: 110 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib"] [workspace.package] -version = "0.2.1" +version = "0.2.2-pre.1" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 157127e..3c34d36 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -46,7 +46,7 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U ### Releases fonctionnelles décidées/pressenties - [X] `0.2.1` — **HTTP transport foundation réduite par le gate `pre.001`** : crate/settings/JSON-RPC/registry 52 current + 14 deprecated historiques, pool/rôles/limites/retry, Config adapter, documentation et 4 méthodes typées canari (`getBalance`, `getGenesisHash`, `getHealth`, `getVersion`) publiés stables. -- [ ] `0.2.2` — Compléter HTTP Accounts + Tokens + Cluster : 5 méthodes Accounts restantes + 5 Tokens + 12 Cluster restantes, soit 22 méthodes. +- [/] `0.2.2` — Compléter HTTP Accounts + Tokens + Cluster : 5 méthodes Accounts restantes + 5 Tokens + 12 Cluster restantes, soit 22 méthodes ; `pre.001` confirme le périmètre officiel et un sizing positif. - [ ] `0.2.3` — Compléter les 11 méthodes HTTP Transactions, y compris write/submission technique avec politique no-resend ambigu. - [ ] `0.2.4` — Compléter les 10 méthodes HTTP Blocks + 5 Economics et exécuter la compliance finale de toute la surface HTTP 52 current + 14 deprecated historiques. - [ ] `0.2.5` — Introduire `ksp-wallet-lib`, le format `.kspwallet`, la gestion sûre des secrets et une architecture d'import/export extensible ; exclure `WalletPolicy`. diff --git a/deltas/0.2.2/pre.001.md b/deltas/0.2.2/pre.001.md new file mode 100644 index 0000000..25e11f1 --- /dev/null +++ b/deltas/0.2.2/pre.001.md @@ -0,0 +1,180 @@ + + + +# 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. diff --git a/docs/000-README.md b/docs/000-README.md index 0111d3a..05eb35c 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation KSP @@ -40,7 +40,8 @@ docs/ │ ├── 005-V0_1_3_CONFIG_FOUNDATION_PLAN.md │ ├── 006-V0_1_4_CONFIG_DESKTOP_PLAN.md │ ├── 007-V0_2_0_SERIES_PLANNING.md -│ └── 008-V0_2_1_ONCHAIN_HTTP_PLAN.md +│ ├── 008-V0_2_1_ONCHAIN_HTTP_PLAN.md +│ └── 009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md ├── validation/ │ ├── 000-README.md │ ├── 001-V0_1_4_CONFIG_DESKTOP.md @@ -62,7 +63,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é ## Documents de planification -Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) devient le point d'entrée de `0.2.2`. +Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) devient le point d'entrée de `0.2.2`. Son `pre.001` ouvre le plan actif [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md), qui confirme après réaudit officiel le périmètre de 22 wrappers typés et son découpage de travail. `IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales. diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index a401197..d48b9bd 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -17,6 +17,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](006-V0_1_4_CONFIG_DESKTOP_PLAN.md) — plan historique clôturé de la release stable `0.1.4 — ksp-app-config-desk`, établi par `0.1.4-pre.001` puis consolidé jusqu'à `0.1.4-rel.001`. - [`007-V0_2_0_SERIES_PLANNING.md`](007-V0_2_0_SERIES_PLANNING.md) — plan historique clôturé de la release stable `0.2.0`, ouvert par `pre.001`, consolidé par `pre.002`, audité par `pre.003` puis publié par `rel.001`; il fixe l'ordre `0.2.1+`, la stratégie RAW/CORE/DECODE/SPECIALIZED, les vertical slices Program et le prompt `0.2.1`. - [`008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](008-V0_2_1_ONCHAIN_HTTP_PLAN.md) — plan de `0.2.1`, établi par `0.2.1-pre.001`, recalibré par `pre.001-fix.001` et amené en clôture candidate par `pre.007`; il conserve l'inventaire 52 méthodes HTTP courantes + 14 Deprecated historiques, le design Transport/Config et le split de couverture typée sur `0.2.1`–`0.2.4`. +- [`009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) — plan actif de `0.2.2`, établi par `0.2.2-pre.001` après réaudit officiel ; il confirme les 22 méthodes Accounts/Tokens/Cluster, leurs formes wire communes et le sizing de la release. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md index 8aabeba..0c4d585 100644 --- a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +++ b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md @@ -1,5 +1,5 @@ - + # Séquence des releases fonctionnelles KSP @@ -390,6 +390,8 @@ Ces trois releases constituent le découpage nominal, pas une obligation de troi Chaque `pre.001` réaudite la documentation officielle actuelle. Les méthodes Deprecated réellement retirées restent tracées comme historiques/runtime removed au lieu d'être simulées. +`0.2.2-pre.001` a effectué ce réaudit : la partition reste 22 méthodes (5 Accounts + 5 Tokens + 12 Cluster) et le gate de sizing est positif. Le plan d'exécution actif est `docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`. + ## `0.2.5` — Wallet foundation Mission : créer `ksp-wallet-lib` et le format `.kspwallet`. diff --git a/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md b/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md new file mode 100644 index 0000000..0fa73e8 --- /dev/null +++ b/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md @@ -0,0 +1,497 @@ + + + +# Plan `0.2.2` — HTTP Accounts + Tokens + Cluster + +## Statut + +Ce plan ouvre `0.2.2-pre.001` sur la base stable `v0.2.1`. + +`0.2.1` a déjà stabilisé la foundation HTTP commune : settings, endpoints/pool/rôles, admission et limites, retry, JSON-RPC 2.0, +registry des méthodes, exécution HTTP générique, adapter Config -> Transport et quatre wrappers typés canari. + +Cette release ne reconstruit aucun transport par famille. Elle complète uniquement la surface typée des 22 méthodes déjà attribuées à +`HttpRpcCoverageRelease::V0_2_2`. + +## Sources normatives réauditées le 2026-08-17 + +Source documentaire principale : + +```text +https://solana.com/docs/rpc/http +``` + +Références complémentaires officielles utilisées pour les formes wire communes : + +```text +https://solana.com/docs/rpc/json-structures +https://github.com/anza-xyz/agave/blob/v3.1.8/rpc/src/rpc.rs +https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/config.rs +https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/filter.rs +https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/request.rs +https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/response.rs +``` + +Les liens `Source` des pages RPC Solana consultées pointent actuellement vers Agave `v3.1.8`. KSP ne prend pas de dépendance sur ces crates : +leur source sert seulement à lever les ambiguïtés de la documentation HTTP lorsque nécessaire. + +## Résultat de l'audit global + +L'index HTTP officiel courant contient toujours **52 méthodes**. Pour les familles concernées par cette release : + +```text +Accounts : 6 current = 1 acquis en 0.2.1 + 5 ciblés en 0.2.2 +Tokens : 5 current = 5 ciblés en 0.2.2 +Cluster : 15 current = 3 acquis en 0.2.1 + 12 ciblés en 0.2.2 +``` + +La navigation officielle Deprecated contient toujours exactement les **14 méthodes historiques** déjà enregistrées dans KSP : + +```text +confirmTransaction +getConfirmedBlock +getConfirmedBlocks +getConfirmedBlocksWithLimit +getConfirmedSignaturesForAddress2 +getConfirmedTransaction +getFeeCalculatorForBlockhash +getFeeRateGovernor +getFees +getRecentBlockhash +getSignatureConfirmation +getSignatureStatus +getSnapshotSlot +getStakeActivation +``` + +Aucune méthode ajoutée, supprimée ou déplacée n'a été détectée par rapport à l'audit `0.2.1` du 2026-08-17. Les 22 méthodes de cette release +restent donc la partition exacte prévue. Les pages courantes ciblées ne portent pas de marqueur Deprecated ou Unstable ; les descriptors KSP +restent `Stable / Supported / Stable`, `Read`, `RetrySafe`. + +## Gate de sizing obligatoire + +Question : + +```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. +``` + +Le périmètre ne nécessite ni nouvelle foundation de transport, ni nouvelle crate, ni nouvelle dépendance externe identifiée à `pre.001`. +Les difficultés sont concentrées dans quelques contrats wire, principalement les données de compte, `getProgramAccounts`, `getLeaderSchedule` +et `getVoteAccounts`. Elles peuvent être isolées dans les prereleases prévues sans compresser les tests. + +Le sizing reste conditionnel à la règle KSP habituelle : si une tranche dépasse réellement le budget de 15–20 minutes, une prerelease +supplémentaire est ajoutée dans `0.2.2`; la release n'est pas artificiellement comprimée et aucune méthode n'est déplacée silencieusement. + +## Matrice exacte — Accounts + +| Méthode | Paramètres/config confirmés | Résultat typé à préserver | Limites / points significatifs | +|-------------------------------------|-----------------------------------------------------------------|-------------------------------------|---------------------------------------------------------------------------------------------------------| +| `getAccountInfo` | `Pubkey`, config `commitment/encoding/dataSlice/minContextSlot` | `RpcResponse>` | compte absent = `null`; erreur min-context distincte | +| `getLargestAccounts` | config `commitment/filter/sortResults` | `RpcResponse>` | 20 résultats; filtre `circulating/nonCirculating`; cache provider possible | +| `getMinimumBalanceForRentExemption` | longueur de données, `commitment?` | `u64` lamports | aucune valeur sentinelle inventée | +| `getMultipleAccounts` | `Vec`, config Account | `RpcResponse>>` | maximum documenté 100; ordre des résultats = ordre demandé | +| `getProgramAccounts` | `Pubkey`, config Account + `filters/withContext/sortResults` | résultat bare ou contextualisé | HTTP documente `dataSize`/`memcmp`; Agave accepte aussi `tokenAccountState`; 4 filtres max côté serveur | + +### Wire Account commun + +Le type `Account` KSP doit rester un DTO de transport, sans décodage Program. Les formes documentées imposent de conserver : + +```text +lamports u64 +owner Pubkey +executable bool +rentEpoch u64 +space Option +data forme wire discriminée +``` + +`data` n'est pas modélisable correctement par un simple `String`. Les formes à conserver sont : + +- chaîne legacy `binary` lorsque le serveur l'émet ; +- couple `[data, encoding]` pour `base58`, `base64` et `base64+zstd` ; +- objet `jsonParsed` lorsque le parser RPC existe ; +- fallback `[data, "base64"]` même lorsqu'un appel demande `jsonParsed` mais qu'aucun parser n'est disponible. + +La valeur `jsonParsed.parsed` reste un `serde_json::Value` au niveau Transport. Aucun modèle SPL/Program n'est introduit ici. + +`dataSlice` est un petit DTO `{ offset, length }`. Il n'impose aucun décodage local des données et ne justifie donc pas l'ajout de `base64` +ou `bs58` dans cette release. + +### `getProgramAccounts` + +Le résultat dépend de `withContext` : + +```text +false/absent -> Vec +true -> RpcResponse> +``` + +Le contrat public doit refléter cette union au lieu de supprimer le contexte ou d'inventer un contexte lorsque le serveur n'en renvoie pas. + +Les filtres KSP doivent distinguer les trois variantes acceptées par la source primaire Agave actuelle : + +```text +DataSize(u64) +Memcmp { offset, bytes, encoding } +TokenAccountState +``` + +Pour `Memcmp`, `base58` est l'encodage implicite lorsque `encoding` est absent; `base58`, `base64` et les octets bruts sont acceptés par le wire +courant, tandis que l'ancien libellé `binary` n'est plus accepté. La donnée comparée est limitée à 128 octets après décodage. Agave expose en +outre `MAX_GET_PROGRAM_ACCOUNT_FILTERS = 4`, même si la page HTTP actuelle ne publie pas cette cardinalité. Le plan retient donc **4 filtres max +comme limite runtime/source primaire à préserver**, en la distinguant explicitement d'une limite publiée sur la page HTTP. + +Cette connaissance n'impose pas l'ajout immédiat de `base64` ou `bs58` à KSP : le DTO peut préserver les chaînes encodées sans les décoder. +Une validation locale de la taille décodée ne sera ajoutée que si elle apporte une valeur claire et justifie la dépendance; le wrapper doit en +revanche empêcher plus de quatre filtres, car cette requête serait refusée par le serveur actuel. + +## Matrice exacte — Tokens + +| Méthode | Paramètres/config confirmés | Résultat typé à préserver | Limites / points significatifs | +|------------------------------|-----------------------------------------------------------------------|-----------------------------------------|-------------------------------------------------------------------| +| `getTokenAccountBalance` | token account `Pubkey`, `commitment?` | `RpcResponse` | erreur RPC si le compte n'est pas exploitable comme token account | +| `getTokenAccountsByDelegate` | delegate `Pubkey`, selector `{mint}` ou `{programId}`, config Account | `RpcResponse>` | selector exclusif par construction | +| `getTokenAccountsByOwner` | owner `Pubkey`, selector `{mint}` ou `{programId}`, config Account | `RpcResponse>` | selector exclusif par construction | +| `getTokenLargestAccounts` | mint `Pubkey`, `commitment?` | `RpcResponse>` | 20 plus gros comptes du mint | +| `getTokenSupply` | mint `Pubkey`, `commitment?` | `RpcResponse` | aucune conversion métier SPL | + +Le selector commun doit rendre impossible la production accidentelle d'un objet contenant simultanément `mint` et `programId`, par exemple avec +un enum KSP `Mint(Pubkey) | ProgramId(Pubkey)` sérialisé vers la forme RPC attendue. + +Le `TokenAmount` wire commun conserve : + +```text +amount String +decimals u8 +uiAmount Option +uiAmountString String +``` + +`uiAmount` est nullable dans les structures JSON officielles ; KSP ne doit pas le remplacer par `0.0`. + +Les deux méthodes de liste réutilisent le DTO Account générique. `jsonParsed` peut contenir des structures SPL, mais Transport les conserve en +JSON sans les convertir en modèle Token métier. + +## Matrice exacte — Cluster + +| Méthode | Paramètres/config confirmés | Résultat typé à préserver | Limites / points significatifs | +|--------------------------|------------------------------------|---------------------------|---------------------------------------------------------------------------------------------| +| `getClusterNodes` | aucun | `Vec` | nombreux endpoints/champs optionnels | +| `getEpochInfo` | config `commitment/minContextSlot` | `EpochInfo` | `transactionCount` nullable | +| `getEpochSchedule` | aucun | `EpochSchedule` | structure fixe d'epoch schedule | +| `getHighestSnapshotSlot` | aucun | `SnapshotSlotInfo` | `incremental` nullable; absence de snapshot = erreur RPC | +| `getIdentity` | aucun | identity `Pubkey` | objet `{identity}` sur le wire | +| `getLeaderSchedule` | slot/config overload | `Option` | forme des paramètres particulière; résultat nullable | +| `getMaxRetransmitSlot` | aucun | `u64` | lecture simple | +| `getMaxShredInsertSlot` | aucun | `u64` | lecture simple | +| `getSlot` | config `commitment/minContextSlot` | `u64` | erreur min-context possible | +| `getSlotLeader` | config `commitment/minContextSlot` | leader `Pubkey` | erreur min-context possible | +| `getSlotLeaders` | `startSlot`, `limit` | `Vec` | limite documentée `1..=5000`; ordre par slot | +| `getVoteAccounts` | config vote accounts | `VoteAccountStatus` | `current` + `delinquent`; Agave borne actuellement `epochCredits` à 5 entrées par validator | + +### `ClusterNode` + +La surface courante documente les champs suivants : + +```text +pubkey Pubkey +featureSet Option +gossip Option +pubsub Option +rpc Option +serveRepair Option +shredVersion Option +tpu Option +tpuForwards Option +tpuForwardsQuic Option +tpuQuic Option +tpuVote Option +tvu Option +version Option +``` + +Même si Agave utilise actuellement `SocketAddr` en interne pour plusieurs endpoints, le DTO public Transport ne doit pas imposer davantage que +le contrat JSON. Les adresses réseau restent donc des chaînes wire optionnelles à moins qu'un invariant officiel plus strict soit nécessaire. + +### `EpochInfo` et `EpochSchedule` + +`EpochInfo` conserve : + +```text +absoluteSlot u64 +blockHeight u64 +epoch u64 +slotIndex u64 +slotsInEpoch u64 +transactionCount Option +``` + +`EpochSchedule` conserve : + +```text +firstNormalEpoch u64 +firstNormalSlot u64 +leaderScheduleSlotOffset u64 +slotsPerEpoch u64 +warmup bool +``` + +### `getHighestSnapshotSlot` + +La page officielle possède les états « Snapshot / No Snapshot ». La source Agave reliée par cette page confirme qu'un noeud sans configuration +snapshot ou sans full snapshot renvoie `RpcCustomError::NoSnapshot`. KSP conserve cette situation comme erreur JSON-RPC applicative ; il ne la +convertit pas en `{ full: 0, incremental: null }`. + +### `getLeaderSchedule` + +La forme actuelle doit être respectée exactement : + +```text +paramètre 1 optionnel : slot u64 | config object | null +paramètre 2 optionnel : config object lorsque le premier paramètre est slot/null +config : commitment + identity +résultat : map identity -> indices de slots relatifs au début de l'epoch, ou null +``` + +Une API Rust typée doit empêcher les combinaisons incohérentes plutôt que demander à l'appelant de construire manuellement ce tableau JSON. + +### `getVoteAccounts` + +La config actuelle contient : + +```text +commitment +votePubkey +keepUnstakedDelinquents +delinquentSlotDistance +``` + +Chaque record conserve au minimum : + +```text +votePubkey Pubkey +nodePubkey Pubkey +activatedStake u64 +commission u8 +epochVoteAccount bool +epochCredits Vec<(epoch u64, credits u64, previousCredits u64)> +lastVote u64 +rootSlot u64 +``` + +Un petit DTO nommé pour une entrée `epochCredits` est préférable à exposer un tuple public opaque, tout en conservant la forme tableau du wire +au décodage. La source Agave courante limite la réponse à cinq entrées d'historique `epochCredits` par validator; KSP ne doit pas supposer que +l'historique complet d'un vote account est exposé par cette méthode RPC. + +## DTOs communs et organisation prévue + +`pre.002` doit introduire des types partagés ciblés, pas un « mega DTO ». Le découpage prévu est conceptuellement : + +```text +RPC context / commitment +account encoding + data slice + account wire +keyed account +program-account filters +token selector + token amount +cluster epoch/schedule/node/snapshot/leader/vote structures +``` + +`SolanaCommitment` et `SolanaRpcContext`, actuellement nés avec les canaris `0.2.1`, doivent être mutualisés sans casser leur réexport public. +Les wrappers continueront à utiliser des structs wire privés `serde` puis une conversion explicite vers les DTOs publics KSP, notamment pour +valider et convertir les chaînes de pubkey vers `ksp_core_lib::Pubkey`. + +Aucune activation anticipée d'une feature `serde` sur `solana-pubkey` n'est nécessaire : la foundation actuelle sait déjà sérialiser une Pubkey +par sa représentation texte, et les réponses peuvent être décodées par wire structs privés avant conversion. + +## Architecture d'exécution imposée + +Tous les wrappers suivent : + +```text +wrapper typé + -> descriptor central + -> execute_standard_rpc + -> pool/admission + -> reqwest HTTP + -> validation JSON-RPC + -> decode typé +``` + +Sont explicitement interdits : + +- client HTTP parallèle par famille ; +- appel `reqwest` direct dans un wrapper ; +- bypass deadline/admission/retry ; +- dépendance Transport -> Config/Store/Program ; +- import direct de `tracing` ; +- conversion des accounts en modèles Program/SPL métier. + +## Erreurs, retry et sécurité + +Les 22 descriptors sont réaudités comme lectures et restent `RetrySafe`. Aucun `WriteSubmission` n'entre dans `0.2.2`. + +Les règles `0.2.1` sont inchangées : + +- erreur JSON-RPC applicative distincte des erreurs transport ; +- `reqwest::Error::without_url()` avant exposition comme source ; +- aucune URL/provider credential/body complet dans diagnostics ou logs ordinaires ; +- retry central uniquement selon descriptor/policy ; +- unique hiérarchie d'erreur via `ksp_core_lib::Error`. + +Les validations de paramètres KSP sont ajoutées seulement lorsqu'elles sont normatives et utiles avant I/O, notamment : + +```text +getMultipleAccounts : <= 100 pubkeys +getProgramAccounts : <= 4 filtres (limite runtime Agave courante) +getSlotLeaders : 1..=5000 +Token selector : exactement mint OU programId +``` + +`minContextSlot` peut produire l'erreur RPC dédiée `MinContextSlotNotReached`; le wrapper ne doit pas la transformer en absence de données. + +## Logging + +Aucun événement par méthode n'est ajouté par défaut. Les événements génériques de Transport restent la source d'observabilité : méthode, +rôle, endpoint logique, tentative et statut technique, avec metadata sûre. + +Toute instrumentation temporaire `debug` ajoutée pendant les prereleases d'implémentation doit revenir à la baseline `info`/`warn` lors de la +tranche finale. + +## Config + +L'audit de `std.transport.json`, de son schema et de `ksp-config-lib/src/transport.rs` ne révèle aucune capacité manquante nécessaire aux 22 +wrappers. Aucun changement Config n'est prévu dans `pre.001`. + +La direction reste strictement : + +```text +ksp-config-lib -> ksp-onchain-transport-lib +``` + +Transport ne lit ni `.env`, ni `std::env`. + +## Dépendances + +Aucune nouvelle dépendance externe n'est requise par le design retenu à `pre.001`. + +En particulier, `base64` et `bs58` ne sont pas nécessaires pour représenter les chaînes encodées du wire. Elles ne seront ajoutées que si une +capacité publique réelle de décodage/validation binaire est décidée ultérieurement, ce qui n'est pas un objectif de `0.2.2`. + +Aucune crate SPL, `solana-client`, SDK RPC haut niveau ou `ksp-interface-lib` n'est introduit pour cette surface. + +## Stratégie de tests + +Chaque wrapper doit disposer de fixtures déterministes et d'un serveur HTTP local couvrant au minimum : + +- sérialisation exacte de la request ; +- réponse success typée ; +- `null`/option pertinent ; +- config/overload pertinent ; +- erreur JSON-RPC significative ; +- cardinalité/selector lorsqu'un invariant est documenté. + +Cas transversaux prioritaires : + +- toutes les variantes Account data réellement supportées ; +- fallback `jsonParsed -> base64` ; +- `space: null` ; +- `getAccountInfo` et `getMultipleAccounts` avec comptes absents ; +- `getProgramAccounts` bare vs `withContext` ; +- `TokenAmount.uiAmount: null` ; +- fields optionnels de `getClusterNodes` ; +- `EpochInfo.transactionCount: null` ; +- `SnapshotSlotInfo.incremental: null` et erreur NoSnapshot ; +- `getLeaderSchedule: null` + overloads ; +- `getVoteAccounts` current/delinquent et epoch credits ; +- limites 100, 4 filtres Program Accounts et 5000; variantes/encodages `memcmp`. + +Les canaries de release doivent maintenir : + +```text +current methods == 52 exactes +historical methods == 14 exactes +coverage partition == 4 / 22 / 11 / 15 +0.2.1 typed canaries == getBalance/getGenesisHash/getHealth/getVersion, inchangés +0.2.2 exact set == les 22 méthodes de ce plan +0.2.3/0.2.4 != typed-complete prématurément +``` + +Un smoke Devnet opt-in pourra couvrir un sous-ensemble représentatif, sans jamais remplacer les fixtures locales. + +## Prévision souple des prereleases + +| Tranche | Objectif | +|-----------|--------------------------------------------------------------------------------------------------------------------| +| `pre.001` | audit officiel actuel, matrice exacte, architecture DTO, dépendances et sizing | +| `pre.002` | primitives/configs/results communs Account/Token/Cluster + fixtures de base; mutualiser Context/Commitment | +| `pre.003` | 5 wrappers Accounts + tests déterministes | +| `pre.004` | 5 wrappers Tokens + tests déterministes | +| `pre.005` | Cluster simple : nodes, epoch info/schedule, snapshot, identity, max retransmit, max shred + tests | +| `pre.006` | Cluster schedule/slot/vote : leader schedule, slot, slot leader(s), vote accounts + tests | +| `pre.007` | canaries de complétude, smoke opt-in si utile, README/USAGE, validation finale, prompt `0.2.3`, préparation stable | + +Le découpage est volontairement asymétrique : `pre.006` contient moins de méthodes mais les formes les plus complexes. Toute tranche qui dépasse +le budget est scindée en une prerelease supplémentaire plutôt que compressée. + +## Hors périmètre + +Sont exclus de `0.2.2` : + +- les 11 méthodes Transactions de `0.2.3` ; +- les 15 méthodes Blocks + Economics de `0.2.4` ; +- WebSocket, Yellowstone, provider-specific streams ; +- décodage SPL/Program ; +- Store/materialization ; +- `ksp-interface-lib` anticipé ; +- modification de Config sans besoin concret ; +- ajout de dépendances de décodage pour simple représentation wire. + +## Validations prévues + +Pendant le développement : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +``` + +À la clôture : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +cargo test -p ksp-config-lib +cargo test -p ksp-core-lib +cargo test --workspace + +cargo tree -p ksp-onchain-transport-lib +cargo tree -p ksp-onchain-transport-lib -d +cargo tree -p ksp-onchain-transport-lib -e features +cargo tree -p ksp-onchain-transport-lib -e normal +``` + +## Critères de clôture `0.2.2` + +`0.2.2` ne devient stable que lorsque : + +- la matrice officielle est réauditée une dernière fois ; +- les 22 méthodes de ce plan ont chacune un wrapper public typé et leurs tests ; +- les quatre canaris `0.2.1` restent inchangés ; +- la partition globale ne perd aucune méthode future ; +- les DTOs conservent les `null`/options documentés ; +- les frontières de dépendances, redaction, retry et logging restent conformes ; +- README/USAGE et validation durable sont synchronisés ; +- les commandes Cargo finales réellement exécutables passent ; +- le prompt `0.2.3 — HTTP Transactions` est prêt ; +- `rel.001` ne contient plus de développement fonctionnel nouveau.