157 lines
5.3 KiB
Markdown
157 lines
5.3 KiB
Markdown
<!-- file: crates/ksp-program-api/README.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# ksp-program-api
|
|
|
|
`ksp-program-api` est la façade publique ouverte du domaine Program KSP. Elle porte uniquement les contrats communs nécessaires aux implémentations Program officielles futures comme aux crates externes ; elle ne possède aucun decoder concret, registry runtime, payload canonique DECODE ni logique d'exécution.
|
|
|
|
La surface candidate de `0.2.14` est volontairement **instruction-only** et reste indépendante des couches runtime supérieures.
|
|
|
|
## Ownership
|
|
|
|
Le graphe normal est limité à :
|
|
|
|
```text
|
|
ksp-program-api
|
|
├── ksp-core-lib
|
|
└── ksp-interface-lib
|
|
└── ksp-core-lib
|
|
```
|
|
|
|
Core reste propriétaire de :
|
|
|
|
```text
|
|
Error
|
|
ErrorCode
|
|
ErrorContext
|
|
Result
|
|
Pubkey
|
|
```
|
|
|
|
Interface reste propriétaire de :
|
|
|
|
```text
|
|
ProgramAccountMeta
|
|
ProgramInstruction
|
|
```
|
|
|
|
Program API possède :
|
|
|
|
```text
|
|
ProgramInstructionRecognition
|
|
ProgramInstructionDecodeOutcome<Decoded>
|
|
ProgramInstructionDecoder
|
|
```
|
|
|
|
`ksp-program-api` réexporte toute sa surface consommable depuis son crate-root. Aucun module interne n'est public.
|
|
|
|
## Surface publique candidate
|
|
|
|
L'inventaire crate-root de `0.2.14` contient exactement :
|
|
|
|
```text
|
|
Error
|
|
ErrorCode
|
|
ErrorContext
|
|
Result
|
|
Pubkey
|
|
ProgramAccountMeta
|
|
ProgramInstruction
|
|
ProgramInstructionRecognition
|
|
ProgramInstructionDecodeOutcome<Decoded>
|
|
ProgramInstructionDecoder
|
|
```
|
|
|
|
Les canaris de release completeness verrouillent cet inventaire ainsi que les trois fichiers/modules Rust de production de la crate.
|
|
|
|
## Recognition
|
|
|
|
`ProgramInstructionRecognition` est `#[non_exhaustive]` :
|
|
|
|
```text
|
|
NoMatch l'implémentation ne revendique pas l'instruction
|
|
ProgramMatch le Program correspond, sans reconnaissance instruction-local exacte
|
|
ExactMatch l'implémentation affirme un match instruction-local exact
|
|
```
|
|
|
|
La reconnaissance ne porte aucun score, priorité, proof, confidence, discriminator textuel ni inventaire central de Programs. `ExactMatch` reste une affirmation de l'implémentation, pas une preuve indépendante produite par KSP.
|
|
|
|
## Decode outcome
|
|
|
|
`ProgramInstructionDecodeOutcome<Decoded>` est `#[non_exhaustive]` :
|
|
|
|
```text
|
|
Decoded(Decoded) valeur typée possédée par l'implémentation
|
|
Unsupported instruction reconnue mais non supportée par cette capability
|
|
```
|
|
|
|
Les échecs réels utilisent le `Result` Core. Il n'existe aucune variante parallèle `Failed` ou `Ignored`.
|
|
|
|
Le `Debug` de l'outcome n'impose pas `Decoded: Debug` et n'affiche jamais la valeur `Decoded`.
|
|
|
|
## Decoder instruction-only
|
|
|
|
`ProgramInstructionDecoder` est un trait ouvert `Send + Sync` :
|
|
|
|
```text
|
|
type Decoded
|
|
program_ids(&self) -> &[Pubkey]
|
|
recognize(&self, &ProgramInstruction) -> ProgramInstructionRecognition
|
|
decode(&self, &ProgramInstruction) -> Result<ProgramInstructionDecodeOutcome<Self::Decoded>>
|
|
```
|
|
|
|
`Decoded` ne reçoit aucun bound implicite supplémentaire : une implémentation reste propriétaire de son type de sortie concret. Le trait ne fournit aucun default method et ne promet pas de composition `dyn` hétérogène.
|
|
|
|
`program_ids()` expose des `Pubkey` opaques ; une implémentation externe peut prendre en charge un Program ID absent du registry Core. Aucun enum central, `Any`, JSON ou descriptor global n'est nécessaire.
|
|
|
|
`program_ids` et `recognize` servent à la sélection explicite. `decode` consomme par référence une `ProgramInstruction` déjà admise/bornée par Interface et déjà sélectionnée pour le decoder.
|
|
|
|
## Hardening validé
|
|
|
|
La candidate verrouille notamment :
|
|
|
|
```text
|
|
Program Pubkey non enregistré accepté
|
|
input Interface maximal 255 accounts + 10_240 bytes accepté à la frontière decoder
|
|
payload hostile aucun echo automatique ajouté par Program API
|
|
Debug outcome valeur Decoded jamais rendue
|
|
associated Decoded aucun Debug/Clone/Send/Sync imposé
|
|
closed-world Program enum absent
|
|
registry / descriptors / priority absents
|
|
ProgramExecutionPreparer absent
|
|
serde / JSON / Any / codecs absents
|
|
logging / runtime / filesystem / environment / I/O absents
|
|
```
|
|
|
|
Une implémentation tierce reste responsable du contenu des erreurs qu'elle construit explicitement. `ksp-program-api` garantit seulement qu'il n'ajoute aucun canal parallèle ni copie automatique du payload d'entrée.
|
|
|
|
## Frontières
|
|
|
|
La foundation `0.2.14` ne contient pas :
|
|
|
|
```text
|
|
ksp-program-lib
|
|
registry runtime
|
|
identity/version/coverage de decoder
|
|
payload canonique D3
|
|
ProgramAccountDecoder
|
|
ProgramEventDecoder
|
|
ProgramReturnDataDecoder
|
|
ProgramExecutionPreparer
|
|
serde / serde_json
|
|
borsh / wincode / bincode
|
|
solana-instruction
|
|
network / async runtime
|
|
logging / tracing
|
|
Wallet / Transport / Store / Materializer / Config / Tauri
|
|
```
|
|
|
|
Ces surfaces restent reportées jusqu'aux vertical slices qui démontreront leurs contrats réels. En particulier, les codecs wire officiels restent possédés par `ksp-interface-lib` et ne sont introduits qu'en présence d'un protocole réel.
|
|
|
|
## Références
|
|
|
|
- [Usage public](USAGE.md)
|
|
- [Plan `0.2.14`](../../docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md)
|
|
- [Validation `0.2.14`](../../docs/validation/017-V0_2_14_PROGRAM_API.md)
|
|
- [Architecture Wire + Program](../../docs/architecture/006-WIRE_AND_PROGRAM.md)
|