135 lines
3.5 KiB
Markdown
135 lines
3.5 KiB
Markdown
<!-- file: ks-program-ids/USAGE.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# Utilisation de ks-program-ids
|
||
|
||
## Objectif
|
||
|
||
La crate fournit des identifiants Solana canoniques et un registre public énumérable.
|
||
|
||
## Utiliser une constante canonique
|
||
|
||
```rust
|
||
let token_program =
|
||
ks_program_ids::SPL_TOKEN_PROGRAM_ID;
|
||
let token_2022_program =
|
||
ks_program_ids::SPL_TOKEN_2022_PROGRAM_ID;
|
||
|
||
assert_ne!(token_program, token_2022_program);
|
||
```
|
||
|
||
Les constantes sont des chaînes Base58. Le consommateur peut les parser dans le type Solana requis par sa propre API.
|
||
|
||
## Parser une constante en `Pubkey`
|
||
|
||
```rust
|
||
use std::str::FromStr; // rust-rules: trait-import
|
||
|
||
let program_id = match solana_pubkey::Pubkey::from_str(
|
||
ks_program_ids::SYSTEM_PROGRAM_ID,
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => {
|
||
return std::result::Result::Err(
|
||
ks_core::Error::new(
|
||
"program_id_invalid",
|
||
error.to_string(),
|
||
),
|
||
);
|
||
},
|
||
};
|
||
```
|
||
|
||
## Parcourir le registre complet
|
||
|
||
```rust
|
||
for entry in ks_program_ids::registered_program_ids() {
|
||
println!(
|
||
"{}={}",
|
||
entry.code(),
|
||
entry.program_id()
|
||
);
|
||
}
|
||
```
|
||
|
||
`entries()` est un alias de compatibilité de `registered_program_ids()`.
|
||
|
||
## Rechercher une adresse exacte
|
||
|
||
```rust
|
||
let entry = ks_program_ids::find_registered_program_id(
|
||
ks_program_ids::SYSTEM_PROGRAM_ID,
|
||
);
|
||
|
||
match entry {
|
||
std::option::Option::Some(value) => {
|
||
assert_eq!(value.code(), "system");
|
||
},
|
||
std::option::Option::None => {
|
||
return std::result::Result::Err(
|
||
ks_core::Error::new(
|
||
"program_id_not_registered",
|
||
"system program must be registered",
|
||
),
|
||
);
|
||
},
|
||
}
|
||
```
|
||
|
||
## Distinguer programmes natifs et comptes connus
|
||
|
||
```rust
|
||
let native_programs =
|
||
ks_program_ids::native_program_ids();
|
||
let native_accounts =
|
||
ks_program_ids::native_well_known_account_ids();
|
||
|
||
assert!(native_programs.iter().any(|entry| {
|
||
entry.program_id()
|
||
== ks_program_ids::SYSTEM_PROGRAM_ID
|
||
}));
|
||
|
||
assert!(native_accounts.iter().any(|entry| {
|
||
entry.program_id()
|
||
== ks_program_ids::STAKE_CONFIG_ACCOUNT_ID
|
||
}));
|
||
```
|
||
|
||
`STAKE_CONFIG_ACCOUNT_ID` désigne un compte connu, pas un programme exécutable. `STAKE_CONFIG_PROGRAM_ID` reste un alias historique de compatibilité.
|
||
|
||
## Construire un ensemble de filtrage
|
||
|
||
```rust
|
||
let supported = [
|
||
ks_program_ids::SPL_MEMO_V4_PROGRAM_ID,
|
||
ks_program_ids::SPL_TOKEN_PROGRAM_ID,
|
||
ks_program_ids::SPL_TOKEN_2022_PROGRAM_ID,
|
||
];
|
||
|
||
let matches = supported.contains(
|
||
&observed_program_id.as_str(),
|
||
);
|
||
```
|
||
|
||
## Erreurs et invariants
|
||
|
||
- les recherches sont exactes et sensibles à la casse ;
|
||
- les codes du registre sont stables et triés ;
|
||
- une constante réservée ne prouve pas l’implémentation d’une surface ;
|
||
- les comptes connus non exécutables doivent rester séparés des programmes ;
|
||
- les sources documentaires futures ne remplacent pas la vérification du code.
|
||
|
||
## Tests de référence
|
||
|
||
- `registry_entries_are_unique_and_non_empty` ;
|
||
- `native_registry_contains_exactly_every_solana_core_surface` ;
|
||
- `stake_config_is_a_well_known_account_not_an_executable_program` ;
|
||
- `registry_lookup_finds_system_program` ;
|
||
- `protocol_primitives_are_registered_without_joining_native_surfaces`.
|
||
|
||
## Limites durables
|
||
|
||
- la crate ne vérifie pas en temps réel le déploiement réseau d’un programme ;
|
||
- elle ne télécharge pas d’IDL ;
|
||
- elle ne détermine pas si une surface est décodée, exécutée ou matérialisée.
|