123 lines
4.0 KiB
Markdown
123 lines
4.0 KiB
Markdown
<!-- file: crates/ksp-interface-lib/USAGE.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Usage de ksp-interface-lib
|
|
|
|
Cette page décrit la façade publique matérialisée par `0.2.13`. Les modules internes ne font pas partie du contrat consommable : utiliser uniquement les exports du crate-root.
|
|
|
|
## Construire des account metas
|
|
|
|
```rust
|
|
let readonly_account = ksp_interface_lib::Pubkey::new_from_array([1_u8; 32]);
|
|
let writable_account = ksp_interface_lib::Pubkey::new_from_array([2_u8; 32]);
|
|
|
|
let readonly = ksp_interface_lib::ProgramAccountMeta::readonly(readonly_account, true);
|
|
let writable = ksp_interface_lib::ProgramAccountMeta::writable(writable_account, false);
|
|
|
|
assert_eq!(readonly.pubkey(), &readonly_account);
|
|
assert!(readonly.is_signer());
|
|
assert!(!readonly.is_writable());
|
|
|
|
assert_eq!(writable.pubkey(), &writable_account);
|
|
assert!(!writable.is_signer());
|
|
assert!(writable.is_writable());
|
|
```
|
|
|
|
`readonly`/`writable` décrivent uniquement les flags wire de l'account meta. Interface ne valide pas l'identité du compte contre un registry Program.
|
|
|
|
## Construire une instruction passive
|
|
|
|
```rust
|
|
let program_id = ksp_interface_lib::Pubkey::new_from_array([3_u8; 32]);
|
|
let account_id = ksp_interface_lib::Pubkey::new_from_array([4_u8; 32]);
|
|
|
|
let account = ksp_interface_lib::ProgramAccountMeta::writable(account_id, true);
|
|
let result = ksp_interface_lib::ProgramInstruction::try_new(
|
|
program_id,
|
|
std::vec![account, account],
|
|
std::vec![7_u8, 8, 9],
|
|
);
|
|
|
|
match result {
|
|
std::result::Result::Ok(instruction) => {
|
|
assert_eq!(instruction.program_id(), &program_id);
|
|
assert_eq!(instruction.accounts(), &[account, account]);
|
|
assert_eq!(instruction.data(), &[7_u8, 8, 9]);
|
|
}
|
|
std::result::Result::Err(error) => {
|
|
eprintln!("{error}");
|
|
}
|
|
}
|
|
```
|
|
|
|
L'ordre et les doublons des accounts sont conservés. Les octets `data` restent opaques : `ProgramInstruction` ne les sérialise, désérialise ni interprète.
|
|
|
|
Les `Vec` fournis à `try_new` sont consommés par la structure après validation des bornes ; aucun clone ou reformatage interne n'est requis par le contrat actuel.
|
|
|
|
## Bornes
|
|
|
|
Les limites publiques sont :
|
|
|
|
```rust
|
|
assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_ACCOUNTS, 255);
|
|
assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_DATA_LEN, 10_240);
|
|
```
|
|
|
|
`255` account metas et `10_240` bytes de data sont admis. `256` account metas ou `10_241` bytes sont refusés par `try_new` avant création d'un `ProgramInstruction` valide.
|
|
|
|
Ces limites sont des bornes locales Interface et ne promettent pas qu'une instruction admise respecte à elle seule toutes les contraintes de taille/account-set d'une transaction Solana complète.
|
|
|
|
## Observer une erreur de limite
|
|
|
|
Le code public est :
|
|
|
|
```rust
|
|
assert_eq!(
|
|
ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.domain(),
|
|
"interface",
|
|
);
|
|
assert_eq!(
|
|
ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.code(),
|
|
"program_instruction_limit_exceeded",
|
|
);
|
|
```
|
|
|
|
Une erreur de dépassement expose uniquement un contexte structurel sûr :
|
|
|
|
```text
|
|
field
|
|
actual_len
|
|
maximum_len
|
|
```
|
|
|
|
Le contenu du payload et les account metas arbitraires ne sont pas projetés dans le diagnostic.
|
|
|
|
## Debug borné
|
|
|
|
Le `Debug` de `ProgramInstruction` contient uniquement :
|
|
|
|
```text
|
|
program_id
|
|
account_count
|
|
data_len
|
|
```
|
|
|
|
Il ne faut donc pas attendre de ce rendu une sérialisation wire ou un dump du payload.
|
|
|
|
## Dépendances à ne pas ajouter côté consumer
|
|
|
|
Un consumer de la façade Interface n'a pas besoin d'ajouter un SDK Program Solana uniquement pour reconstruire `ProgramInstruction`. La crate utilise le `Pubkey` canonique partagé avec Core et conserve son propre contrat passif.
|
|
|
|
La foundation ne fournit volontairement pas :
|
|
|
|
```text
|
|
serde générique
|
|
Borsh / Wincode générique
|
|
solana-instruction interop automatique
|
|
transport réseau
|
|
Program decoder/preparer
|
|
signing/execution
|
|
```
|
|
|
|
Ces surfaces doivent être introduites dans leur owner respectif lorsqu'un cas réel le justifie, pas comme dépendances implicites d'un consumer Interface.
|