125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
<!-- file: crates/ksp-program-api/README.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# ksp-program-api
|
|
|
|
`ksp-program-api` est la façade publique ouverte du domaine Program KSP. Elle est destinée aux implémentations officielles futures comme aux crates Program externes et ne possède pas les implémentations concrètes.
|
|
|
|
À partir de `0.2.14-pre.003`, la foundation expose les types Core/Interface retenus ainsi que le vocabulaire minimal de reconnaissance et d'outcome de décodage. Le trait decoder reste réservé à la tranche suivante.
|
|
|
|
## Ownership
|
|
|
|
La crate dépend uniquement de :
|
|
|
|
```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 désormais :
|
|
|
|
```text
|
|
ProgramInstructionRecognition
|
|
ProgramInstructionDecodeOutcome<Decoded>
|
|
```
|
|
|
|
`ksp-program-api` réexporte l'ensemble depuis son crate-root pour offrir une façade de consommation stable sans dupliquer les types Core/Interface ni transférer leur ownership.
|
|
|
|
## Recognition
|
|
|
|
`ProgramInstructionRecognition` est `#[non_exhaustive]` et possède trois états :
|
|
|
|
```text
|
|
NoMatch l'implémentation ne revendique pas l'instruction
|
|
ProgramMatch le Program ou la famille correspond, sans reconnaissance exacte
|
|
ExactMatch l'implémentation affirme un match instruction-local exact
|
|
```
|
|
|
|
Cette reconnaissance ne contient aucun score, priorité, proof, confidence, discriminator textuel ou inventaire central de Programs.
|
|
|
|
## Decode outcome
|
|
|
|
`ProgramInstructionDecodeOutcome<Decoded>` est également `#[non_exhaustive]` :
|
|
|
|
```text
|
|
Decoded(Decoded) valeur typée possédée par l'implémentation
|
|
Unsupported instruction connue mais non supportée par cette capability
|
|
```
|
|
|
|
Un futur `decode(...)` utilisera le `Result` Core : une erreur de validation/décodage restera donc `Err`, sans variante parallèle `Failed`.
|
|
|
|
Le `Debug` de l'outcome n'impose pas `Decoded: Debug` et n'affiche jamais la valeur `Decoded`. Il produit uniquement le nom sûr de l'état (`Decoded` ou `Unsupported`).
|
|
|
|
## Surface actuelle
|
|
|
|
La façade `pre.003` expose :
|
|
|
|
```text
|
|
Error
|
|
ErrorCode
|
|
ErrorContext
|
|
Result
|
|
Pubkey
|
|
ProgramAccountMeta
|
|
ProgramInstruction
|
|
ProgramInstructionRecognition
|
|
ProgramInstructionDecodeOutcome<Decoded>
|
|
```
|
|
|
|
Aucun module interne n'est public.
|
|
|
|
Le contrat suivant reste réservé à `pre.004` :
|
|
|
|
```text
|
|
ProgramInstructionDecoder
|
|
```
|
|
|
|
## Frontières
|
|
|
|
La foundation 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
|
|
```
|
|
|
|
L'absence de ces surfaces est volontaire : `ksp-program-api` reste une API déclarative, ouverte et indépendante des implémentations/runtime supérieurs.
|
|
|
|
## 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)
|