286 lines
9.0 KiB
Markdown
286 lines
9.0 KiB
Markdown
<!-- 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
|
|
```
|