v0.2.14-pre.002

crates/ksp-program-api/USAGE.md

@@ -0,0 +1,55 @@
+<!-- file: crates/ksp-program-api/USAGE.md -->
+<!-- version: 1 -->
+
+# Usage de ksp-program-api
+
+Cette page décrit le scaffold public disponible à partir de `0.2.14-pre.002`. Utiliser uniquement les exports du crate-root ; aucun module interne ne fait partie du contrat consommable.
+
+## Construire un input Program avec la façade
+
+```rust
+let program_id = ksp_program_api::Pubkey::new_from_array([1_u8; 32]);
+let account_id = ksp_program_api::Pubkey::new_from_array([2_u8; 32]);
+let account = ksp_program_api::ProgramAccountMeta::readonly(account_id, true);
+
+let instruction = ksp_program_api::ProgramInstruction::try_new(
+    program_id,
+    std::vec![account],
+    std::vec![0x01_u8, 0x02, 0x03],
+);
+
+assert!(instruction.is_ok());
+```
+
+`Pubkey`, `ProgramAccountMeta` et `ProgramInstruction` conservent leur ownership Core/Interface. Program API fournit seulement une façade cohérente aux futures implémentations de capability Program.
+
+## Utiliser le contrat d'erreur commun
+
+Les types d'erreur Core sont également disponibles depuis la façade :
+
+```rust
+fn forward_result(
+    value: ksp_program_api::Result<ksp_program_api::ProgramInstruction>,
+) -> ksp_program_api::Result<ksp_program_api::ProgramInstruction> {
+    return value;
+}
+```
+
+Aucun type d'erreur Program spécifique n'est nécessaire au scaffold.
+
+## Ce que `pre.002` ne fournit pas
+
+Il n'existe encore aucun :
+
+```text
+recognize(...)
+decode(...)
+ProgramInstructionRecognition
+ProgramInstructionDecodeOutcome
+ProgramInstructionDecoder
+registry de decoders
+payload générique JSON/Any
+execution preparer
+```
+
+Ces éléments ne doivent pas être simulés côté consumer. Les contrats de recognition/outcome puis le trait decoder seront introduits dans leurs tranches dédiées.