khadhroony-solana-project/deltas/0.1.1/pre.001-fix.001.md

Delta 0.1.1-pre.001-fix.001

Base requise

Livraison précédente appliquée et commitée :

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

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 :

0.1.1-pre.1

Le correctif possède néanmoins son identifiant de livraison/commit propre :

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 :

ksp-core-lib -> solana-pubkey

lorsque pre.003 implémentera réellement la surface Program IDs.

En revanche :

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 :

PRGID_<SUFFIXE>   : &'static str
PRGIDPK_<SUFFIXE> : Pubkey

Le suffixe doit être strictement identique entre les deux formes.

La nomenclature générale est :

<PREFIX>_<DOMAIN>_<SUBDOMAIN?>_<NAME>_<VERSION?>

Exemples de convention :

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 :

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 :

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 :

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 :

Error / Result

pre.003 est précisé :

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é :

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 :

0.1.1-pre.002 — Error/Result et fondation API