0.5.1-pre.002

ks-program-ids/USAGE.md

@@ -0,0 +1,134 @@
+<!-- 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.