Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4e2647cce1694e97fd99fa0481959f7ec6d5fe0d
khadhroony-solana-project/prompts/007-V0_2_2_START_PROMPT.md
SinuS Von SifriduS 79b67f8eae v0.2.1-pre.007
2026-08-17 22:43:07 +02:00

13 KiB
Raw Blame History

Prompt de démarrage 0.2.2 — HTTP Accounts + Tokens + Cluster

1. Contexte de reprise

La base attendue est la release stable :

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 :

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 :

0.2.2 — HTTP Accounts + Tokens + Cluster

La première tranche est :

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

getAccountInfo
getLargestAccounts
getMinimumBalanceForRentExemption
getMultipleAccounts
getProgramAccounts

getBalance est déjà acquis en 0.2.1 et ne doit pas être réimplémenté.

Tokens — 5

getTokenAccountBalance
getTokenAccountsByDelegate
getTokenAccountsByOwner
getTokenLargestAccounts
getTokenSupply

Cluster — 12

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 :

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 :

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 :

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 :

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 :

ksp_logging_lib
crate::TRACING_TARGET

Le target reste :

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 :

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 :

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 :

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-onchain-transport-lib

À la clôture :

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.
Reference in New Issue View Git Blame Copy Permalink