<!-- file: kb-program-ids/USAGE.md -->
<!-- version: 1 -->

# Utilisation de kb-program-ids

## Objectif

La crate fournit des identifiants Solana canoniques et un registre public énumérable.

## Utiliser une constante canonique

```rust
let token_program =
    kb_program_ids::SPL_TOKEN_PROGRAM_ID;
let token_2022_program =
    kb_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(
    kb_program_ids::SYSTEM_PROGRAM_ID,
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => {
        return std::result::Result::Err(
            kb_core::Error::new(
                "program_id_invalid",
                error.to_string(),
            ),
        );
    },
};
```

## Parcourir le registre complet

```rust
for entry in kb_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 = kb_program_ids::find_registered_program_id(
    kb_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(
            kb_core::Error::new(
                "program_id_not_registered",
                "system program must be registered",
            ),
        );
    },
}
```

## Distinguer programmes natifs et comptes connus

```rust
let native_programs =
    kb_program_ids::native_program_ids();
let native_accounts =
    kb_program_ids::native_well_known_account_ids();

assert!(native_programs.iter().any(|entry| {
    entry.program_id()
        == kb_program_ids::SYSTEM_PROGRAM_ID
}));

assert!(native_accounts.iter().any(|entry| {
    entry.program_id()
        == kb_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 = [
    kb_program_ids::SPL_MEMO_V4_PROGRAM_ID,
    kb_program_ids::SPL_TOKEN_PROGRAM_ID,
    kb_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.