136 lines
3.7 KiB
Markdown
136 lines
3.7 KiB
Markdown
<!-- file: crates/ksp-core-lib/README.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# `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<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 :
|
|
|
|
```text
|
|
<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 :
|
|
|
|
```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.
|