# `ksp-core-lib` `ksp-core-lib` porte les contrats fondamentaux partagés par les couches KSP sans dépendre des domaines de plus haut niveau. La crate possède actuellement trois responsabilités : - le type d'erreur commun KSP ; - le type Solana `Pubkey` réexporté comme primitive d'adresse canonique ; - le registre KSP des Program IDs Solana fondamentaux et leur taxonomie. ## Frontière architecturale Core reste une couche basse. Elle ne possède ni configuration, ni logging runtime, ni transport réseau, ni wallet, ni stockage, ni logique de décodage/exécution. Les crates de niveau supérieur peuvent dépendre de Core et réutiliser ses contrats ; Core ne doit pas introduire de dépendance inverse vers ces couches. La seule dépendance runtime externe directe actuelle est `solana-pubkey`, utilisée pour la primitive `Pubkey`. ## Erreur commune KSP Le contrat d'erreur public repose sur : ```text ErrorCode ErrorContext Error Result ``` `ErrorCode` sépare un `domain` stable d'un `code` stable. `Error` ajoute : - un message humain ; - des champs de contexte ordonnés ; - une source d'erreur standard optionnelle compatible `Send + Sync`. L'affichage d'une erreur reste compact : ```text .: ``` Les consommateurs ajoutent uniquement des contextes sûrs. Les secrets, credentials, key material, URLs sensibles ou payloads massifs ne doivent pas être copiés dans le message ou le contexte d'une erreur. ## `Pubkey` La crate réexporte : ```rust ksp_core_lib::Pubkey ``` Les autres crates KSP utilisent cette primitive lorsqu'un contrat public a besoin d'une adresse Solana générique. Elles évitent ainsi de multiplier les propriétaires de type pour la même notion. ## Program IDs fondamentaux Core possède 18 Program IDs Solana fondamentaux sous deux formes cohérentes : ```text PRGID_* -> Base58 &str PRGIDPK_* -> Pubkey typé ``` Les deux formes sont déclarées depuis une même valeur grâce à `declare_program_id!`. Le registre couvre notamment : - System, Vote, Stake, Config et Feature ; - Address Lookup Table et Compute Budget ; - les loaders natif, BPF v1, BPF v2, BPF upgradeable et Loader v4 ; - les precompiles Ed25519, Secp256k1 et Secp256r1 ; - Slashing ; - ZK ElGamal Proof et ZK Token Proof. Le registre n'est pas un catalogue général de tous les programmes Solana. Les protocoles, applications et Program IDs de domaines futurs sont ajoutés dans les couches propriétaires appropriées lorsqu'un besoin réel existe. ## Registre et taxonomie Chaque entrée est exposée sous `ProgramIdEntry` avec : ```text code name program_id pubkey domain family protocol subfamily program_version kind ``` `ProgramIdKind` distingue actuellement : ```text Program Loader Precompile EnshrinedProgram ``` La lecture du registre s'effectue par : ```text entries() native_program_ids() program_ids(filter) program_ids_by_domain(...) program_ids_by_family(...) program_ids_by_protocol(...) find_program_id(...) find_program_pubkey(...) ``` `ProgramIdFilter` permet de combiner les axes `domain`, `family`, `protocol`, `subfamily`, `program_version` et `kind`. ## Garanties validées Les tests publics et unitaires verrouillent notamment : - la correspondance Base58 / `Pubkey` des constantes ; - l'unicité des codes, Program IDs et pubkeys du registre ; - les 18 entrées fondamentales ; - les recherches textuelles et typées ; - les vues et filtres taxonomiques ; - l'absence des comptes well-known qui ne sont pas des programmes ; - le contrat `Error`, son ordre de contexte et sa chaîne `source()` ; - `Error: Send + Sync`. ## Documentation - [`USAGE.md`](USAGE.md) — exemples d'utilisation de l'erreur commune, de `Pubkey`, des Program IDs et du registre.