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

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

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 :

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 :

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 :

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 :

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.

3.3 KiB Raw Blame History