Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.1.1-pre.001-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-14 14:26:43 +02:00
parent ecc82f681d
commit 37a1480c72
2 changed files with 435 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Plan KSP 0.1.1 — Core foundation
@@ -26,7 +26,7 @@ Constats sur l'archive reçue :
- le delta final `deltas/0.0.3/rel.001.md` indique que les validations Cargo de publication ont été exécutées avec succès par le user avant stabilisation ;
- le prompt `prompts/001-V0_1_1_START_PROMPT.md` présent dans l'archive correspond au prompt final attendu pour cette session.
L'archive ne contient pas `.git`. L'état du working tree réel, le commit stable et le tag `v0.0.3` ne peuvent donc pas être vérifiés depuis cette archive et restent à confirmer sur le dépôt Git réel avant commit de `0.1.1-pre.001`.
Dans le workflow KSP, l'archive `khadhroony-solana-project-v0.0.3.zip` est produite directement par Gitea depuis le tag correspondant. Cette provenance suffit à considérer la base fournie comme la release stable/taguée `v0.0.3` attendue ; l'absence normale de `.git` dans l'archive n'ajoute pas de vérification Git supplémentaire à cette session.
## Mission bornée
@@ -36,7 +36,7 @@ La surface retenue pour cette release est limitée à :
1. un contrat commun `Error` / `Result` ouvert aux domaines supérieurs ;
2. la primitive Solana d'adresse publique nécessaire aux Program IDs ;
3. les Program IDs fondamentaux du runtime Solana ;
3. les Program IDs fondamentaux du runtime Solana, leurs deux représentations canonique texte/`Pubkey` et un petit registre descriptif enumerable ;
4. les réexports crate-root, rustdocs et tests nécessaires à ces contrats.
Aucune autre primitive n'est ajoutée sans usage concret découvert pendant la release.
@@ -55,9 +55,9 @@ Les Program IDs ont besoin d'une représentation Solana typée et commune. Core
### Program IDs fondamentaux
Core doit posséder les identifiants du runtime Solana qui ne relèvent d'aucun protocole supérieur.
Core doit posséder les identifiants fondamentaux du runtime Solana qui ne relèvent d'aucun protocole supérieur.
Cette responsabilité ne signifie pas qu'il doit posséder un registre de dispatch, des decoders, des instructions wire ou une taxonomie de protocoles.
Cette propriété inclut les valeurs canoniques KSP, leur représentation `Pubkey`, leur nomenclature et un registre descriptif enumerable permettant de les inventorier/rechercher. Ce registre de constantes n'est pas le registry de dispatch de `ksp-program-lib` : il ne sélectionne aucun decoder, executor ou implémentation de programme et ne crée aucune enum fermée des protocoles.
## Contrat d'erreur proposé
@@ -125,6 +125,11 @@ ksp_core_lib::ErrorCode
ksp_core_lib::ErrorContext
ksp_core_lib::Result
ksp_core_lib::Pubkey
ksp_core_lib::ProgramIdEntry
ksp_core_lib::entries
ksp_core_lib::native_program_ids
ksp_core_lib::find_program_id
ksp_core_lib::declare_program_id!
```
Les modules d'implémentation restent privés conformément aux règles Rust du dépôt.
@@ -181,17 +186,17 @@ Elle n'est pas ajoutée directement à KSP en `0.1.1` : l'ajouter en parallèle
### `solana-sdk-ids`
La source officielle `solana-sdk-ids` expose les identifiants canoniques du runtime et s'appuie sur `solana-address`.
La source officielle `solana-sdk-ids` reste utile comme référence d'audit des identifiants publiés par Anza/Solana.
État du package observé :
État du package observé pendant `pre.001` :
```text
solana-sdk-ids 3.1.0
```
Décision proposée : ne pas en faire une dépendance runtime de Core. KSP possède ses noms publics et constantes Core, construits avec `Pubkey`.
Décision acquise : **ne pas ajouter `solana-sdk-ids` à KSP**, ni comme dépendance runtime, ni comme dev-dependency.
En revanche, `solana-sdk-ids` est un bon candidat de **dev-dependency uniquement** en `pre.003` pour vérifier que les constantes KSP correspondent aux identifiants officiels. Son ajout devra être confirmé par le test concret et revérifié au moment de l'implémentation.
KSP possède ses propres constantes et registres de Program IDs. Les sources officielles Anza/Solana sont consultées pour vérifier les valeurs et l'évolution de la surface, mais cette vérification ne doit pas créer une dépendance Cargo à leur crate d'IDs.
### Crates explicitement non nécessaires à `0.1.1`
@@ -210,58 +215,146 @@ La génération actuelle de `solana-pubkey` requiert Rust 1.89.0. Avant son ajou
## Program IDs retenus pour la première surface Core
La première surface doit contenir uniquement les Program IDs fondamentaux actuellement exposés par la source officielle `solana-sdk-ids`, y compris les loaders et précompiles qui font partie de la frontière runtime :
Le nombre exact de Program IDs de la première surface Core n'est plus figé à `17`.
```text
ADDRESS_LOOKUP_TABLE_PROGRAM_ID
BPF_LOADER_PROGRAM_ID
BPF_LOADER_DEPRECATED_PROGRAM_ID
BPF_LOADER_UPGRADEABLE_PROGRAM_ID
COMPUTE_BUDGET_PROGRAM_ID
CONFIG_PROGRAM_ID
ED25519_PROGRAM_ID
FEATURE_PROGRAM_ID
LOADER_V4_PROGRAM_ID
NATIVE_LOADER_PROGRAM_ID
SECP256K1_PROGRAM_ID
SECP256R1_PROGRAM_ID
STAKE_PROGRAM_ID
SYSTEM_PROGRAM_ID
VOTE_PROGRAM_ID
ZK_ELGAMAL_PROOF_PROGRAM_ID
ZK_TOKEN_PROOF_PROGRAM_ID
```
`pre.001` retient les familles fondamentales suivantes comme inventaire de départ à vérifier une dernière fois contre les sources officielles au moment de `pre.003` :
Les noms KSP définitifs seront confirmés au moment du code, mais doivent rester explicites et crate-root.
- System ;
- Stake ;
- Vote ;
- Config ;
- Feature ;
- Compute Budget ;
- Address Lookup Table ;
- loaders BPF historiques/actuels et Loader v4 ;
- Native Loader ;
- précompiles Ed25519, Secp256k1 et Secp256r1 ;
- programmes ZK fondamentaux actuellement exposés par la surface Anza/Solana ;
- tout programme natif/historique supplémentaire réellement encore pertinent pour la frontière Core.
### Exclusions volontaires
L'ancien `ks-program-ids` de bot3 est utilisé comme inventaire historique complémentaire, pas comme source de vérité. Il rappelle notamment une entrée `slashing` dans son ensemble `native_program_ids()`. Sa présence dans la première surface KSP doit être décidée à partir de son statut officiel réel au moment de `pre.003`, plutôt que déduite d'un nombre figé ou d'une ancienne liste.
Ne pas inclure dans cette première liste :
### Exclusions volontaires de `0.1.1`
Ne pas ajouter fonctionnellement pendant cette release :
- SPL Token, Token-2022, ATA, Memo ou tout autre protocole SPL ;
- Metaplex et autres protocoles ;
- `incinerator`, qui est une adresse spéciale et non un Program ID exécutable ;
- le compte historique `stake::config` ;
- les sysvar account IDs ;
- un registre enumerable `ProgramIdEntry` ;
- une classification native/protocole destinée au futur `ksp-program-api` ;
- des alias de compatibilité historiques venant de bot3.
- les autres well-known accounts non exécutables uniquement pour agrandir la première surface.
Les well-known account IDs pourront être ajoutés plus tard si un consommateur Core réel les nécessite. Ils ne doivent pas être confondus avec les Program IDs simplement pour agrandir la première surface.
Les exemples SPL/protocoles utilisés pour définir la nomenclature ci-dessous illustrent la convention future et ne modifient pas le hors-scope de `0.1.1`.
Les well-known account IDs doivent rester explicitement séparés des Program IDs. L'ancien `native_well_known_account_ids()` constitue une bonne direction conceptuelle ; aucune API vide n'est toutefois créée en `0.1.1` tant qu'aucun well-known account n'est réellement retenu dans la surface de la release.
## Nomenclature des Program IDs
Chaque Program ID KSP possède deux représentations publiques partageant exactement le même suffixe :
```text
PRGID_<DOMAIN>_<SUBDOMAIN?>_<NAME>_<VERSION?> -> &'static str Base58
PRGIDPK_<DOMAIN>_<SUBDOMAIN?>_<NAME>_<VERSION?> -> Pubkey
```
Règles :
- `PRGID_` identifie toujours la représentation texte Base58 ;
- `PRGIDPK_` identifie toujours la représentation `Pubkey` ;
- le suffixe après le préfixe doit être identique entre les deux formes ;
- `DOMAIN` identifie le propriétaire/famille stable, par exemple `SOLANA`, `SPL`, `METAPLEX`, `RAYDIUM` ;
- `SUBDOMAIN` n'est utilisé que lorsqu'il clarifie réellement une famille interne ;
- `VERSION` n'est ajoutée que lorsque plusieurs Program IDs distincts correspondent réellement à des versions différentes ;
- la nomenclature privilégie propriétaire/famille puis fonction, afin d'éviter les anciens noms inversés difficiles à étendre.
Exemples de convention :
```text
PRGID_SOLANA_SYSTEM
PRGIDPK_SOLANA_SYSTEM
PRGID_SOLANA_LOADER_BPF_V2
PRGIDPK_SOLANA_LOADER_BPF_V2
PRGID_SOLANA_PRECOMPILE_ED25519
PRGIDPK_SOLANA_PRECOMPILE_ED25519
PRGID_SPL_MEMO_V3
PRGIDPK_SPL_MEMO_V3
```
`PRGID_SPL_MEMO_V3` est uniquement un exemple de nomenclature future pendant `0.1.1` ; SPL Memo reste hors scope fonctionnel de cette release.
## Construction et ownership des constantes
Les constantes KSP doivent être des valeurs typées `Pubkey` produites à la compilation à partir des adresses canoniques vérifiées.
KSP possède la chaîne Base58 canonique de chaque Program ID et ne dépend pas d'un registre runtime externe pour la fournir.
KSP ne dépend pas d'un registre runtime externe pour les obtenir.
La chaîne Base58 ne doit être écrite qu'une seule fois dans la déclaration KSP. Une macro publique KSP, nommée initialement `declare_program_id!`, doit produire les deux représentations à partir d'une déclaration unique, selon une forme conceptuelle de ce type :
La source officielle Solana/Anza sert :
```text
declare_program_id!(
PRGID_SOLANA_SYSTEM,
PRGIDPK_SOLANA_SYSTEM,
"11111111111111111111111111111111"
);
```
1. de source de vérité pour la valeur ;
2. éventuellement de référence de test via `solana-sdk-ids` en dev-dependency ;
3. de contrôle lors des audits de version.
Le résultat conceptuel est :
Le code ne doit pas recopier d'architecture ou d'API supérieure de `solana-sdk-ids` au-delà des constantes réellement nécessaires.
```text
PRGID_SOLANA_SYSTEM : &'static str
PRGIDPK_SOLANA_SYSTEM : Pubkey
```
La macro doit s'inspirer de la mécanique compile-time de `solana_address::declare_id!`/des primitives correspondantes exposées via la génération `solana-pubkey`, mais KSP possède son API et sa nomenclature. L'implémentation exacte sera vérifiée en `pre.003` contre la version réellement retenue de `solana-pubkey`.
Invariants :
- aucune seconde copie manuelle de la valeur Base58 ;
- aucune conversion runtime inutile ;
- aucun `unwrap`, `expect`, `panic` ou opérateur `?` ;
- les deux constantes sont disponibles au crate-root ;
- la macro n'impose pas les symboles génériques `ID`, `id()` ou `check_id()` qui entreraient en collision lorsque plusieurs Program IDs sont déclarés dans Core.
Les sources officielles Solana/Anza servent :
1. de source de vérité externe pour vérifier la valeur Base58 ;
2. de contrôle de l'évolution des IDs/runtime ;
3. de référence d'audit ponctuelle sans dépendance Cargo.
## Registre descriptif des Program IDs
L'ancien `ks-program-ids` fournissait notamment :
```text
ProgramIdEntry
entries()
registered_program_ids()
native_program_ids()
native_well_known_account_ids()
find_registered_program_id()
```
Cette fonctionnalité doit être reprise et simplifiée/améliorée dans Core pour les IDs réellement possédés par Core.
Direction retenue :
- `ProgramIdEntry` décrit une entrée canonique KSP sans porter de decoder/executor ;
- `entries()` expose toutes les entrées Program ID actuellement possédées par Core ;
- `native_program_ids()` expose le sous-ensemble runtime-native/loader/precompile/historique retenu par Core ;
- `find_program_id()` recherche une entrée par Program ID canonique ;
- une recherche directe par `Pubkey` peut être ajoutée si elle simplifie réellement l'usage sans dupliquer la logique ;
- `registered_program_ids()` de bot3 est considéré comme un alias redondant de `entries()` et n'est pas repris automatiquement ;
- les well-known accounts suivent un registre/naming distinct lorsqu'ils deviennent nécessaires.
`ProgramIdEntry` doit au minimum pouvoir exposer :
- un code KSP stable lisible machine ;
- la représentation Base58 `PRGID_*` ;
- la représentation `Pubkey` `PRGIDPK_*` ;
- une classification minimale permettant de construire les sous-ensembles utiles sans dupliquer manuellement plusieurs registres.
La structure Rust exacte et le nom exact de la classification sont finalisés avec les tests de `pre.003`. Cette classification reste descriptive et bornée aux catégories réellement nécessaires ; elle ne devient pas une enum générale de protocoles ou de capacités de décodage.
## Primitives communes supplémentaires
@@ -303,12 +396,14 @@ Tests unitaires externes pour vérifier les invariants internes éventuels.
Tests d'intégration pour vérifier :
- `ksp_core_lib::Pubkey` consommable depuis la façade ;
- type exact des constantes ;
- valeurs attendues des Program IDs ;
- unicité des 17 Program IDs retenus ;
- conformité aux IDs officiels via `solana-sdk-ids` si la dev-dependency est retenue.
- type exact des constantes `PRGID_*` et `PRGIDPK_*` ;
- égalité entre chaque chaîne Base58 possédée par KSP et sa représentation `Pubkey` compile-time ;
- unicité des codes, chaînes Base58 et `Pubkey` du registre ;
- cohérence de `entries()`, `native_program_ids()` et `find_program_id()` ;
- séparation entre Program IDs et well-known accounts ;
- conformité des valeurs avec les sources officielles Anza/Solana consultées par l'audit, sans dépendance `solana-sdk-ids`.
L'ordre d'une liste de test ne devient pas un contrat public si aucune liste n'est exposée par l'API.
L'ordre de `entries()` ne devient un contrat public que s'il est explicitement documenté comme tel ; sinon les tests doivent vérifier les invariants sans imposer arbitrairement un ordre.
## Validations prévues
@@ -372,9 +467,11 @@ Objectifs :
- vérifier `rustc` par rapport au MSRV de la génération retenue ;
- ajouter `solana-pubkey` uniquement au propriétaire `ksp-core-lib` ;
- réexporter `Pubkey` ;
- implémenter les 17 Program IDs retenus ;
- ajouter les tests de conformité ;
- décider et, si utile, ajouter `solana-sdk-ids` uniquement en dev-dependency ;
- implémenter `declare_program_id!` et la paire `PRGID_*` / `PRGIDPK_*` ;
- finaliser l'inventaire des Program IDs fondamentaux à partir des sources officielles actuelles ;
- implémenter `ProgramIdEntry`, `entries()`, `native_program_ids()` et `find_program_id()` ;
- ajouter les tests de conformité et d'unicité ;
- confirmer l'absence totale de dépendance `solana-sdk-ids` ;
- auditer le graphe/features réels.
### `0.1.1-pre.004` — intégration Core + audits
@@ -427,7 +524,7 @@ Un `pre.NNN-fix.NNN` corrige la tranche correspondante sans réécrire son histo
- Confirmer, pendant `pre.002`, si `ErrorContext` doit être ajouté par une méthode consommant `self` (`with_context`) ou par une méthode mutable ; privilégier l'API la plus simple compatible avec le style explicite KSP.
- Confirmer le format exact de `Display` par les tests avant de le considérer stable.
- Revérifier en `pre.003` les versions publiées de `solana-pubkey` et `solana-sdk-ids` ainsi que le MSRV officiel au jour du code.
- Revérifier en `pre.003` la version publiée de `solana-pubkey`, son API compile-time pertinente et le MSRV officiel au jour du code.
- Décider en `pre.005`, à partir de l'API réellement stabilisée, si un `README.md`/`USAGE.md` de crate apporte suffisamment de valeur pour être créé maintenant.
Aucune de ces questions ne justifie d'élargir le périmètre fonctionnel de `0.1.1`.