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 :

ErrorCode
ErrorContext
Error
Result<T>

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 :

<domain>.<code>: <message>

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 :

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 :

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 :

code
name
program_id
pubkey
domain
family
protocol
subfamily
program_version
kind

ProgramIdKind distingue actuellement :

Program
Loader
Precompile
EnshrinedProgram

La lecture du registre s'effectue par :

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 — exemples d'utilisation de l'erreur commune, de Pubkey, des Program IDs et du registre.