432 lines
13 KiB
Markdown
432 lines
13 KiB
Markdown
<!-- file: prompts/007-V0_2_2_START_PROMPT.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Prompt de démarrage `0.2.2` — HTTP Accounts + Tokens + Cluster
|
||
|
||
## 1. Contexte de reprise
|
||
|
||
La base attendue est la release stable :
|
||
|
||
```text
|
||
v0.2.1
|
||
```
|
||
|
||
`0.2.1` a stabilisé `ksp-onchain-transport-lib` comme foundation HTTP Solana : settings runtime, endpoints/pool/rôles, limites et résilience, JSON-RPC 2.0, registry audité, exécution HTTP générique, Config -> Transport et quatre wrappers typés canari.
|
||
|
||
Les invariants à préserver sont notamment :
|
||
|
||
```text
|
||
52 méthodes HTTP courantes auditées
|
||
14 méthodes historiques Deprecated / runtime Removed
|
||
4 wrappers typés acquis : getBalance/getGenesisHash/getHealth/getVersion
|
||
partition planifiée : 4 / 22 / 11 / 15 sur 0.2.1–0.2.4
|
||
Transport -X-> Config/Store/Program/tracing direct
|
||
Config -> Transport autorisé
|
||
no-resend après dispatch ambigu pour WriteSubmission
|
||
URLs/provider credentials absents des diagnostics ordinaires
|
||
```
|
||
|
||
La release à ouvrir est :
|
||
|
||
```text
|
||
0.2.2 — HTTP Accounts + Tokens + Cluster
|
||
```
|
||
|
||
La première tranche est :
|
||
|
||
```text
|
||
0.2.2-pre.001
|
||
```
|
||
|
||
`pre.001` commence par **audit officiel actuel + brainstorming + dimensionnement** avant implémentation lourde.
|
||
|
||
## 2. Mission
|
||
|
||
Compléter la surface **typée** KSP des familles Accounts, Tokens et Cluster restantes, en réutilisant sans duplication la foundation HTTP de `0.2.1`.
|
||
|
||
La cible issue du plan `0.2.1` contient actuellement 22 méthodes :
|
||
|
||
### Accounts — 5
|
||
|
||
```text
|
||
getAccountInfo
|
||
getLargestAccounts
|
||
getMinimumBalanceForRentExemption
|
||
getMultipleAccounts
|
||
getProgramAccounts
|
||
```
|
||
|
||
`getBalance` est déjà acquis en `0.2.1` et ne doit pas être réimplémenté.
|
||
|
||
### Tokens — 5
|
||
|
||
```text
|
||
getTokenAccountBalance
|
||
getTokenAccountsByDelegate
|
||
getTokenAccountsByOwner
|
||
getTokenLargestAccounts
|
||
getTokenSupply
|
||
```
|
||
|
||
### Cluster — 12
|
||
|
||
```text
|
||
getClusterNodes
|
||
getEpochInfo
|
||
getEpochSchedule
|
||
getHighestSnapshotSlot
|
||
getIdentity
|
||
getLeaderSchedule
|
||
getMaxRetransmitSlot
|
||
getMaxShredInsertSlot
|
||
getSlot
|
||
getSlotLeader
|
||
getSlotLeaders
|
||
getVoteAccounts
|
||
```
|
||
|
||
`getGenesisHash`, `getHealth` et `getVersion` sont déjà acquis en `0.2.1`.
|
||
|
||
Ces 22 noms sont la **partition KSP actuellement planifiée**, pas une vérité externe immuable. `pre.001` doit revérifier la documentation Solana du jour avant de confirmer le périmètre.
|
||
|
||
## 3. Sources internes obligatoires
|
||
|
||
Relire avant modification :
|
||
|
||
```text
|
||
ROADMAP.md
|
||
CHANGELOG.md
|
||
RULES.md
|
||
|
||
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||
docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
|
||
docs/validation/003-V0_2_1_ONCHAIN_HTTP.md
|
||
|
||
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
|
||
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||
docs/architecture/004-COMPONENT_INVENTORY.md
|
||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||
|
||
docs/rules/RULES_DEPENDENCIES.md
|
||
docs/rules/RULES_RUST.md
|
||
docs/rules/RULES_KSP.md
|
||
docs/rules/FILE_CONTRACTS.md
|
||
docs/rules/VERSION_WORKFLOW.md
|
||
docs/rules/PROMPT_STRUCTURE.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/
|
||
|
||
crates/ksp-config-lib/src/transport.rs
|
||
config/std.transport.json
|
||
config/schemas/std.transport.schema.json
|
||
```
|
||
|
||
Les deltas `0.2.1` servent de trace historique ; ne pas les réécrire.
|
||
|
||
## 4. Sources externes normatives
|
||
|
||
Au début de `pre.001`, consulter la documentation officielle **actuelle** Solana :
|
||
|
||
```text
|
||
https://solana.com/docs/rpc/http
|
||
```
|
||
|
||
Pour chaque méthode cible, revérifier :
|
||
|
||
- nom exact ;
|
||
- catégorie ;
|
||
- paramètres et ordre ;
|
||
- limites de cardinalité ;
|
||
- objets config ;
|
||
- commitment/minContextSlot ;
|
||
- encoding/dataSlice/filters ;
|
||
- nullable/optional ;
|
||
- forme exacte du résultat ;
|
||
- champs versionnés/optionnels ;
|
||
- erreurs significatives ;
|
||
- statut stable/deprecated/unstable ;
|
||
- éventuelle évolution depuis l'audit du 2026-08-17.
|
||
|
||
Revérifier également l'index global afin de détecter une méthode ajoutée/supprimée/déplacée depuis `0.2.1`.
|
||
|
||
Pour une question technique sur une crate externe, utiliser uniquement sa documentation/source primaire actuelle.
|
||
|
||
## 5. Gate de sizing obligatoire
|
||
|
||
Avant implémentation, répondre explicitement :
|
||
|
||
```text
|
||
Les 22 wrappers typés + DTOs partagés + tests + documentation peuvent-ils être clôturés proprement dans cette session ?
|
||
```
|
||
|
||
Si NON :
|
||
|
||
- ne pas compresser artificiellement la release ;
|
||
- proposer immédiatement un split cohérent de `0.2.2` avant développement lourd ;
|
||
- mettre à jour la séquence sans perdre aucune méthode.
|
||
|
||
Une prerelease vise environ 15–20 minutes de travail effectif.
|
||
|
||
## 6. Architecture à préserver
|
||
|
||
Ne pas reconstruire un second transport par famille.
|
||
|
||
Le flux reste :
|
||
|
||
```text
|
||
wrapper typé
|
||
-> descriptor central
|
||
-> execute_standard_rpc
|
||
-> pool/admission
|
||
-> reqwest HTTP
|
||
-> JSON-RPC validation
|
||
-> decode typé
|
||
```
|
||
|
||
Réutiliser :
|
||
|
||
- `HttpTransportPool` ;
|
||
- `HttpRpcMethodDescriptor` ;
|
||
- `HttpRpcCoverageRelease` ;
|
||
- request kinds ;
|
||
- retry metadata ;
|
||
- JSON-RPC KSP ;
|
||
- erreurs KSP ;
|
||
- Logging KSP ;
|
||
- redaction existante.
|
||
|
||
Aucun wrapper typé ne doit bypasser le pool, la deadline, le retry ou le contrôle central de statut.
|
||
|
||
## 7. DTOs et wire HTTP
|
||
|
||
Créer des types KSP dédiés à la surface HTTP lorsque cela améliore réellement le contrat public.
|
||
|
||
Principes :
|
||
|
||
- utiliser `ksp_core_lib::Pubkey` pour les adresses publiques ;
|
||
- ne pas ajouter `solana-client` ni SDK RPC haut niveau ;
|
||
- ne pas dépendre de Store ou Program ;
|
||
- ne pas introduire `ksp-interface-lib` par anticipation ;
|
||
- ne pas décoder des programmes/accounts métier dans Transport ;
|
||
- conserver les valeurs JSON parsed/encoded à un niveau transport approprié ;
|
||
- ajouter `base64`, `bs58` ou autre dépendance seulement si le contrat typé retenu en a réellement besoin après audit ;
|
||
- mutualiser les objets réellement communs (`context`, account data/config, token amount, filters, epoch/leader structures) sans créer un « mega DTO » artificiel.
|
||
|
||
Les types de résultats doivent conserver les `null` et options documentés au lieu d'inventer des valeurs.
|
||
|
||
## 8. Accounts
|
||
|
||
Auditer et typer notamment :
|
||
|
||
- account absent vs présent ;
|
||
- `encoding` ;
|
||
- `dataSlice` ;
|
||
- `filters` de `getProgramAccounts` ;
|
||
- `withContext` ;
|
||
- `sortResults` si toujours documenté ;
|
||
- limites documentées de `getMultipleAccounts` ;
|
||
- rent exemption ;
|
||
- largest accounts et filtres éventuels.
|
||
|
||
Ne pas convertir une réponse account en modèle Program/décodé.
|
||
|
||
## 9. Tokens
|
||
|
||
Les méthodes Token restent du **transport RPC standard Solana**, pas du decoding SPL Program.
|
||
|
||
Auditer :
|
||
|
||
- `TokenAmount` ;
|
||
- owner/delegate ;
|
||
- filtre exclusif `{mint}` ou `{programId}` ;
|
||
- encodings/dataSlice ;
|
||
- `minContextSlot` ;
|
||
- largest accounts ;
|
||
- supply.
|
||
|
||
Aucune dépendance directe à une crate SPL n'est ajoutée uniquement pour représenter le JSON RPC si des DTOs KSP simples suffisent.
|
||
|
||
## 10. Cluster
|
||
|
||
Auditer précisément les formes de :
|
||
|
||
- node contact info ;
|
||
- epoch info/schedule ;
|
||
- snapshot slots ;
|
||
- identity ;
|
||
- leader schedule et slot leaders ;
|
||
- max retransmit/shred slots ;
|
||
- slot ;
|
||
- vote accounts.
|
||
|
||
Conserver les champs optionnels/versionnés documentés et ne pas supposer qu'un provider retourne toujours toutes les extensions.
|
||
|
||
## 11. Surface raw vs typed
|
||
|
||
`execute_standard_rpc()` reste public et utile, mais :
|
||
|
||
> un appel raw/générique ne compte jamais comme couverture typée de `0.2.2`.
|
||
|
||
Une méthode cible est clôturée seulement lorsque son wrapper public, ses paramètres/configs, son résultat et ses tests sont présents selon la matrice de la release.
|
||
|
||
## 12. Erreurs, retry et sécurité
|
||
|
||
Conserver les invariants `0.2.1` :
|
||
|
||
- JSON-RPC application error distincte d'une erreur transport ;
|
||
- timeout/connection/status remappés sans URL sensible ;
|
||
- `reqwest::Error::without_url()` avant exposition comme source ;
|
||
- aucune URL/token/body complet dans `Debug`/logs ;
|
||
- retry uniquement selon descriptor/policy ;
|
||
- pas de nouvelle hiérarchie d'erreurs locale parallèle à `ksp_core_lib::Error`.
|
||
|
||
Toutes les nouvelles méthodes de `0.2.2` sont a priori des reads, mais `pre.001` doit vérifier leur statut/opération actuel au lieu de l'assumer silencieusement.
|
||
|
||
## 13. Logging
|
||
|
||
Utiliser uniquement :
|
||
|
||
```text
|
||
ksp_logging_lib
|
||
crate::TRACING_TARGET
|
||
```
|
||
|
||
Le target reste :
|
||
|
||
```text
|
||
ksp-onchain-transport-lib
|
||
```
|
||
|
||
Éviter les logs par méthode redondants. Préférer les événements génériques du transport avec metadata sûre : méthode, rôle, endpoint logique, tentative, statut technique.
|
||
|
||
Un niveau `debug` ciblé peut être rouvert temporairement pendant le développement, puis doit revenir à `info`/`warn` dans la dernière prerelease conformément aux règles KSP.
|
||
|
||
## 14. Config
|
||
|
||
Ne modifier `std.transport.json` ou son schema que si une capacité réellement nécessaire de `0.2.2` ne peut pas être exprimée par le contrat existant.
|
||
|
||
La direction reste :
|
||
|
||
```text
|
||
ksp-config-lib -> ksp-onchain-transport-lib
|
||
```
|
||
|
||
Transport ne lit jamais `.env` ou `std::env::var*`.
|
||
|
||
## 15. Tests
|
||
|
||
Pour chaque méthode typée, couvrir au minimum :
|
||
|
||
- sérialisation de la request ;
|
||
- résultat success ;
|
||
- nullable/optional pertinent ;
|
||
- config/overload pertinent ;
|
||
- erreur significative ;
|
||
- invariants de cardinalité/filtre lorsque documentés.
|
||
|
||
Utiliser fixtures déterministes et serveur HTTP local ; Internet est interdit aux tests par défaut.
|
||
|
||
Conserver/étendre les canaries de release :
|
||
|
||
```text
|
||
current == inventaire officiel confirmé
|
||
historical == inventaire officiel confirmé
|
||
partition de couverture exacte
|
||
0.2.1 canaries inchangés
|
||
0.2.2 exact method set
|
||
aucune méthode 0.2.3/0.2.4 déclarée typed-complete prématurément
|
||
```
|
||
|
||
Un smoke Devnet opt-in peut tester un sous-ensemble représentatif, mais il ne remplace pas les fixtures.
|
||
|
||
## 16. Dépendances Cargo
|
||
|
||
Rappels :
|
||
|
||
- versions/default-features communes au root `[workspace.dependencies]` ;
|
||
- features d'usage activées dans chaque crate consommatrice ;
|
||
- toute nouvelle dépendance externe commune est d'abord déclarée au root ;
|
||
- `cargo tree` normal/doublons/features est rejoué lorsqu'une dépendance ou feature change.
|
||
|
||
Ne pas ajouter une dépendance uniquement parce que bot3 l'utilisait.
|
||
|
||
## 17. Documentation et clôture
|
||
|
||
La dernière prerelease de `0.2.2` doit :
|
||
|
||
- réauditer la matrice officielle ;
|
||
- exécuter les canaries finales ;
|
||
- mettre à jour README/USAGE si la surface publique change ;
|
||
- mettre à jour la validation durable ;
|
||
- ramener le logging temporairement élevé à sa baseline ;
|
||
- préparer le prompt `0.2.3 — HTTP Transactions` ;
|
||
- préparer un `rel.001` minimal.
|
||
|
||
`CHANGELOG.md` reçoit l'entrée `0.2.2` au moment de la publication stable, pas comme journal de prereleases.
|
||
|
||
## 18. Prévision souple initiale
|
||
|
||
À confirmer par `pre.001` :
|
||
|
||
| Tranche | Objectif indicatif |
|
||
|-----------|----------------------------------------------------------------------------------------|
|
||
| `pre.001` | re-audit officiel, matrice exacte, DTOs communs, dépendances, sizing |
|
||
| `pre.002` | primitives/configs/results communs Accounts/Token + fixtures de base |
|
||
| `pre.003` | 5 méthodes Accounts typées + tests |
|
||
| `pre.004` | 5 méthodes Tokens typées + tests |
|
||
| `pre.005` | première moitié des 12 méthodes Cluster + tests |
|
||
| `pre.006` | seconde moitié Cluster + tests |
|
||
| `pre.007` | canaries de complétude, smoke opt-in, docs finales, prompt `0.2.3`, préparation stable |
|
||
|
||
Ce tableau n'est pas contractuel. Scinder une tranche si elle dépasse le budget ; ne jamais compresser un groupe pour conserver artificiellement un numéro.
|
||
|
||
## 19. Validations minimales
|
||
|
||
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
|
||
```
|
||
|
||
Ne jamais déclarer une commande réussie si elle n'a pas été exécutée.
|
||
|
||
## 20. Critères de sortie
|
||
|
||
`0.2.2` peut devenir stable seulement si :
|
||
|
||
- l'inventaire officiel actuel est revérifié ;
|
||
- les méthodes ciblées sont précisément celles retenues après cet audit ;
|
||
- chaque méthode cible possède un contrat public typé et des tests déterministes ;
|
||
- les quatre canaris `0.2.1` restent inchangés ;
|
||
- la partition globale ne perd aucune méthode future ;
|
||
- aucune dépendance/frontière KSP n'est violée ;
|
||
- redaction/retry/logging restent conformes ;
|
||
- README/USAGE sont à jour ;
|
||
- validations Cargo et canaries passent ;
|
||
- prompt `0.2.3` est prêt ;
|
||
- `rel.001` ne contient plus de développement fonctionnel nouveau.
|