v0.1.1-pre.001-fix.001
This commit is contained in:
285
deltas/0.1.1/pre.001-fix.001.md
Normal file
285
deltas/0.1.1/pre.001-fix.001.md
Normal file
@@ -0,0 +1,285 @@
|
||||
<!-- file: deltas/0.1.1/pre.001-fix.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.1.1-pre.001-fix.001
|
||||
|
||||
## Base requise
|
||||
|
||||
Livraison précédente appliquée et commitée :
|
||||
|
||||
```text
|
||||
0.1.1-pre.001
|
||||
```
|
||||
|
||||
La base stable initiale `khadhroony-solana-project-v0.0.3.zip` provient directement de Gitea depuis le tag `v0.0.3`. L'absence de `.git` dans cette archive n'impose donc aucune vérification supplémentaire du tag pour le cadrage de cette session.
|
||||
|
||||
## Type de livraison
|
||||
|
||||
```text
|
||||
ksp-doc-0.1.1-pre.001-fix.001.zip
|
||||
```
|
||||
|
||||
## Objectif
|
||||
|
||||
Corriger le plan de `0.1.1-pre.001` après validation du brainstorming Program IDs, sans ouvrir `pre.002` et sans modifier de code/runtime.
|
||||
|
||||
Ce correctif :
|
||||
|
||||
- confirme `solana-pubkey` comme dépendance Solana fondamentale candidate de Core ;
|
||||
- interdit `solana-sdk-ids` comme dépendance KSP, y compris de développement ;
|
||||
- fait posséder à KSP ses chaînes Base58 et représentations `Pubkey` de Program IDs ;
|
||||
- fixe les préfixes `PRGID_` et `PRGIDPK_` ;
|
||||
- fixe la structure générale de nomenclature `<PREFIX>_<DOMAIN>_<SUBDOMAIN?>_<NAME>_<VERSION?>` ;
|
||||
- prévoit une macro KSP `declare_program_id!` produisant les deux représentations depuis une déclaration unique ;
|
||||
- réintroduit et améliore le concept de registre descriptif enumerable inspiré de l'ancien `ks-program-ids` ;
|
||||
- supprime le nombre arbitrairement figé de 17 Program IDs avant l'inventaire final de `pre.003` ;
|
||||
- maintient la séparation stricte entre Program IDs et well-known accounts.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
Aucun fichier participant au code, build, runtime, à la configuration exécutable ou aux migrations n'est modifié.
|
||||
|
||||
Conformément à `VER-ID-008`, `workspace.package.version` reste donc :
|
||||
|
||||
```text
|
||||
0.1.1-pre.1
|
||||
```
|
||||
|
||||
Le correctif possède néanmoins son identifiant de livraison/commit propre :
|
||||
|
||||
```text
|
||||
0.1.1-pre.001-fix.001
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `deltas/0.1.1/pre.001-fix.001.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md` — version documentaire 1 -> 2.
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Corrections et décisions incorporées
|
||||
|
||||
### Provenance de la base stable
|
||||
|
||||
La réserve de `pre.001` liée à l'absence de `.git` dans l'archive Gitea est retirée du plan actif.
|
||||
|
||||
Dans le workflow KSP fourni, une archive nommée `khadhroony-solana-project-vX.Y.Z.zip` est produite directement par Gitea depuis le tag correspondant. `khadhroony-solana-project-v0.0.3.zip` est donc acceptée comme base stable/taguée `v0.0.3`.
|
||||
|
||||
Le delta `pre.001` déjà livré n'est pas réécrit ; ce correctif trace explicitement la correction.
|
||||
|
||||
### Dépendances Solana/Anza
|
||||
|
||||
Direction acquise :
|
||||
|
||||
```text
|
||||
ksp-core-lib -> solana-pubkey
|
||||
```
|
||||
|
||||
lorsque `pre.003` implémentera réellement la surface Program IDs.
|
||||
|
||||
En revanche :
|
||||
|
||||
```text
|
||||
ksp-core-lib -X-> solana-sdk-ids
|
||||
```
|
||||
|
||||
s'applique aux dépendances runtime **et** de développement.
|
||||
|
||||
`solana-sdk-ids` peut être consultée comme source officielle externe lors des audits, mais elle ne doit pas entrer dans le graphe Cargo KSP.
|
||||
|
||||
### Ownership et représentations des Program IDs
|
||||
|
||||
KSP possède la valeur Base58 canonique de chaque Program ID retenu.
|
||||
|
||||
Chaque ID expose deux représentations publiques liées :
|
||||
|
||||
```text
|
||||
PRGID_<SUFFIXE> : &'static str
|
||||
PRGIDPK_<SUFFIXE> : Pubkey
|
||||
```
|
||||
|
||||
Le suffixe doit être strictement identique entre les deux formes.
|
||||
|
||||
La nomenclature générale est :
|
||||
|
||||
```text
|
||||
<PREFIX>_<DOMAIN>_<SUBDOMAIN?>_<NAME>_<VERSION?>
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
L'exemple SPL Memo définit uniquement la convention future ; il n'ouvre pas SPL dans le périmètre fonctionnel de `0.1.1`.
|
||||
|
||||
### Macro de déclaration
|
||||
|
||||
Le plan prévoit une macro publique KSP initialement nommée :
|
||||
|
||||
```text
|
||||
declare_program_id!
|
||||
```
|
||||
|
||||
Elle doit prendre une seule valeur Base58 canonique et produire les deux constantes `PRGID_*` et `PRGIDPK_*` correspondantes à la compilation.
|
||||
|
||||
La macro doit s'inspirer de la mécanique compile-time de `solana_address::declare_id!`/des primitives accessibles via la génération retenue de `solana-pubkey`, tout en conservant une API KSP adaptée à plusieurs Program IDs dans la même crate.
|
||||
|
||||
Elle ne doit notamment pas imposer des symboles génériques `ID`, `id()` ou `check_id()` qui entreraient en collision entre plusieurs déclarations.
|
||||
|
||||
### Registre descriptif enumerable
|
||||
|
||||
Le rejet initial d'un `ProgramIdEntry` enumerable est annulé.
|
||||
|
||||
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()
|
||||
```
|
||||
|
||||
La surface KSP doit reprendre/améliorer les capacités utiles sans reprendre les redondances historiques.
|
||||
|
||||
Direction de `pre.003` :
|
||||
|
||||
```text
|
||||
ProgramIdEntry
|
||||
entries()
|
||||
native_program_ids()
|
||||
find_program_id()
|
||||
```
|
||||
|
||||
Une recherche typée par `Pubkey` reste autorisée si son utilité est démontrée pendant l'implémentation.
|
||||
|
||||
`registered_program_ids()` n'est pas repris automatiquement s'il ne fait que dupliquer `entries()`.
|
||||
|
||||
`ProgramIdEntry` doit pouvoir exposer au minimum un code KSP stable, les formes `PRGID_*`/`PRGIDPK_*` et une classification descriptive minimale permettant les sous-ensembles utiles sans dupliquer plusieurs registres.
|
||||
|
||||
### Program IDs fondamentaux
|
||||
|
||||
La liste de `pre.001` n'est plus figée à 17 entrées.
|
||||
|
||||
L'inventaire final sera confirmé dans `pre.003` contre les sources officielles actuelles, en couvrant notamment :
|
||||
|
||||
- System, Stake, Vote, Config, Feature et Compute Budget ;
|
||||
- Address Lookup Table ;
|
||||
- loaders BPF historiques/actuels, Loader v4 et Native Loader ;
|
||||
- précompiles Ed25519, Secp256k1 et Secp256r1 ;
|
||||
- programmes ZK fondamentaux encore pertinents ;
|
||||
- toute surface native/historique supplémentaire réellement justifiée.
|
||||
|
||||
L'ancien `ks-program-ids` reste un inventaire historique utile. Son entrée `slashing` doit par exemple être réévaluée selon son statut officiel actuel plutôt que retenue ou rejetée uniquement parce qu'elle figurait dans bot3.
|
||||
|
||||
### Program IDs et well-known accounts
|
||||
|
||||
Les Program IDs exécutables et les well-known account IDs restent deux concepts distincts.
|
||||
|
||||
`PRGID_*` / `PRGIDPK_*` ne doivent jamais nommer un compte connu non exécutable.
|
||||
|
||||
Le concept historique `native_well_known_account_ids()` est conservé comme direction architecturale possible, mais `0.1.1` ne crée pas une API vide pour ce domaine si aucun well-known account n'est retenu dans sa surface réelle.
|
||||
|
||||
## Impact sur les prereleases suivantes
|
||||
|
||||
`pre.002` ne change pas :
|
||||
|
||||
```text
|
||||
Error / Result
|
||||
```
|
||||
|
||||
`pre.003` est précisé :
|
||||
|
||||
```text
|
||||
Pubkey
|
||||
+ declare_program_id!
|
||||
+ PRGID_* / PRGIDPK_*
|
||||
+ inventaire final des Program IDs fondamentaux
|
||||
+ ProgramIdEntry / entries() / native_program_ids() / find_program_id()
|
||||
+ tests de conformité/unicité
|
||||
```
|
||||
|
||||
Aucune dépendance `solana-sdk-ids` ne doit y être ajoutée.
|
||||
|
||||
## Hors scope inchangé
|
||||
|
||||
Le correctif n'ouvre toujours pas :
|
||||
|
||||
- Logging ;
|
||||
- Config ;
|
||||
- Tauri ;
|
||||
- Wallet/signing ;
|
||||
- codecs wire ;
|
||||
- Interface ;
|
||||
- Program decoding/dispatch registry/`ProgramExecutionPreparer` ;
|
||||
- execution policy/orchestration ;
|
||||
- Transport ;
|
||||
- Store ;
|
||||
- Materializer ;
|
||||
- workers/jobs/pipelines ;
|
||||
- scenarios ;
|
||||
- trading/ML.
|
||||
|
||||
## Validations exécutées
|
||||
|
||||
- relecture des règles `VERSION_WORKFLOW.md` et `FILE_CONTRACTS.md` de la base stable ;
|
||||
- confirmation qu'un fix purement documentaire ne modifie pas la version Cargo ;
|
||||
- réaudit ciblé de l'ancien `ks-program-ids` fourni dans l'archive bot3 de référence : `ProgramIdEntry`, `entries()`, `registered_program_ids()`, `native_program_ids()`, `native_well_known_account_ids()` et `find_registered_program_id()` ;
|
||||
- relecture du plan `003-V0_1_1_CORE_FOUNDATION_PLAN.md` après correction ;
|
||||
- contrôle statique du header/version des fichiers livrés ;
|
||||
- contrôle des fins de fichiers ;
|
||||
- contrôle de la structure et du contenu de l'archive ;
|
||||
- vérification de l'absence de fichier Cargo/code/runtime dans ce correctif.
|
||||
|
||||
## Validations non exécutées
|
||||
|
||||
Aucune validation Cargo n'est déclarée pour ce correctif documentaire.
|
||||
|
||||
Les commandes suivantes ne sont pas nécessaires pour démontrer le contenu de ce delta, qui ne modifie aucun artefact compilé :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Elles restent les validations attendues dès la prochaine tranche Rust applicable.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
Les décisions nécessaires pour quitter `pre.001` sont considérées validées.
|
||||
|
||||
Les points d'implémentation suivants sont volontairement reportés à leur tranche propriétaire sans bloquer `pre.002` :
|
||||
|
||||
- structure Rust exacte et classification minimale de `ProgramIdEntry` en `pre.003` ;
|
||||
- présence éventuelle d'une recherche dédiée par `Pubkey` ;
|
||||
- inventaire final des IDs natifs/historiques à partir des sources officielles actuelles ;
|
||||
- détail d'expansion de `declare_program_id!` selon l'API exacte de la version `solana-pubkey` retenue.
|
||||
|
||||
## Suite
|
||||
|
||||
Après validation/commit de ce correctif :
|
||||
|
||||
```text
|
||||
0.1.1-pre.002 — Error/Result et fondation API
|
||||
```
|
||||
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user