107 lines
3.3 KiB
Markdown
107 lines
3.3 KiB
Markdown
<!-- file: crates/ksp-program-api/USAGE.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Usage de ksp-program-api
|
|
|
|
Cette page décrit la surface publique disponible à partir de `0.2.14-pre.003`. 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.
|
|
|
|
## Représenter une reconnaissance
|
|
|
|
```rust
|
|
let recognition = ksp_program_api::ProgramInstructionRecognition::ProgramMatch;
|
|
|
|
match recognition {
|
|
ksp_program_api::ProgramInstructionRecognition::NoMatch => {}
|
|
ksp_program_api::ProgramInstructionRecognition::ProgramMatch => {}
|
|
ksp_program_api::ProgramInstructionRecognition::ExactMatch => {}
|
|
_ => {}
|
|
}
|
|
```
|
|
|
|
Le wildcard est volontaire : l'enum est `#[non_exhaustive]` afin de ne pas transformer la foundation en vocabulaire fermé pour toujours.
|
|
|
|
## Représenter un outcome de décodage
|
|
|
|
Le type décodé reste possédé par l'implémentation :
|
|
|
|
```rust
|
|
struct ExternalDecodedInstruction {
|
|
opcode: u8,
|
|
}
|
|
|
|
let outcome = ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(
|
|
ExternalDecodedInstruction { opcode: 7_u8 },
|
|
);
|
|
|
|
match outcome {
|
|
ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(value) => {
|
|
assert_eq!(value.opcode, 7_u8);
|
|
}
|
|
ksp_program_api::ProgramInstructionDecodeOutcome::Unsupported => {}
|
|
_ => {}
|
|
}
|
|
```
|
|
|
|
Aucun `Any`, JSON ou enum centrale n'est nécessaire pour transporter ce type.
|
|
|
|
## Debug sûr
|
|
|
|
`ProgramInstructionDecodeOutcome<Decoded>` possède un `Debug` volontairement opaque sur la valeur décodée :
|
|
|
|
```rust
|
|
struct SecretDecoded;
|
|
|
|
let outcome = ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(SecretDecoded);
|
|
assert_eq!(std::format!("{outcome:?}"), "Decoded");
|
|
```
|
|
|
|
`SecretDecoded` n'a même pas besoin d'implémenter `Debug`. Cela empêche un diagnostic générique de rendre accidentellement un payload externe.
|
|
|
|
## Utiliser le contrat d'erreur commun
|
|
|
|
Les types d'erreur Core restent 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;
|
|
}
|
|
```
|
|
|
|
Le futur `decode(...)` utilisera ce `Result`. Une erreur sera donc `Err(...)`, tandis que `Unsupported` signifie une instruction connue volontairement non prise en charge.
|
|
|
|
## Ce que `pre.003` ne fournit pas
|
|
|
|
Il n'existe encore aucun :
|
|
|
|
```text
|
|
ProgramInstructionDecoder
|
|
program_ids(...)
|
|
recognize(...) sur un trait
|
|
decode(...) sur un trait
|
|
registry de decoders
|
|
payload générique JSON/Any
|
|
execution preparer
|
|
```
|
|
|
|
Ces éléments ne doivent pas être simulés côté consumer. Le trait decoder et la preuve d'implémentation externe sont réservés à `pre.004`.
|