v0.1.0-pre.071

kb-program-ids/CHANGELOG.md

@@ -0,0 +1,18 @@
+<!-- file: kb-program-ids/CHANGELOG.md -->
+<!-- version: 1 -->
+
+# CHANGELOG — kb-program-ids
+
+## 0.1.0-pre.071
+
+- réécriture du README comme référence de la façade publique bot3 ;
+- ajout du TODO, du guide d’utilisation et du changelog de crate ;
+- clarification de la différence entre Program ID réservé et surface implémentée ;
+- documentation du futur registre de sources Program IDs et IDL.
+
+## 0.1.0-pre.062
+
+- migration et consolidation du registre bot2 ;
+- conservation des identifiants Solana Core, SPL et des protocoles réservés ;
+- maintien de la séparation entre programmes natifs exécutables et comptes connus ;
+- adaptation aux normes Rust 2024 et Khadhroony bot3.

kb-program-ids/README.md

@@ -1,25 +1,38 @@
 <!-- file: kb-program-ids/README.md -->
-<!-- version: 7 -->
+<!-- version: 8 -->
 
 # kb-program-ids
 
-`kb-program-ids` est la source unique des identifiants de programmes Solana et des comptes natifs connus utilisés par le workspace.
+`kb-program-ids` est la source Rust canonique des Program IDs Solana et des comptes connus utilisés par le workspace.
 
-La tranche `0.1.0-pre.004` expose les 18 surfaces exécutables nécessaires au décodeur Solana Core, les comptes natifs associés utilisés par leurs contrats et l’identifiant SPL Token classique employé par les tests de frontière. La tranche `0.1.0-pre.005` ajoute les trois identifiants SPL Memo v1, v3 et v4 sans les classer parmi les surfaces natives. `0.1.0-pre.006` active l’identifiant SPL Token classique dans un décodeur concret tout en le maintenant hors des surfaces natives. `0.1.0-pre.007` ajoute les identifiants SPL Associated Token Account et Token‑2022 nécessaires à la frontière ATA. `0.1.0-pre.008` ajoute le Program ID indépendant du registre ElGamal de Token‑2022. `0.1.0-pre.009` ajoute le Program ID indépendant de Metaplex Token Metadata. Ces programmes restent hors des surfaces natives.
+## Responsabilités
 
-La tranche `0.1.0-pre.012` restaure 97 Program IDs supplémentaires utilisés par les squelettes réservés de `kb-lib`. Le registre contient désormais 130 codes et 130 adresses uniques. La réservation Anchor ne possède volontairement aucun Program ID statique.
+- exposer les constantes Base58 canoniques ;
+- fournir un registre énumérable et trié ;
+- distinguer les programmes natifs exécutables des comptes natifs connus ;
+- offrir une recherche exacte par adresse ;
+- réserver les identifiants nécessaires aux surfaces futures sans les déclarer implémentées.
 
-`constants.rs` reste l’unique source des adresses et des tableaux statiques. `programs.rs` porte
-`ProgramIdEntry`, ses méthodes et toutes les fonctions de consultation. `lib.rs` se limite aux
-déclarations de modules et aux réexports documentés de la façade.
+La présence d’un Program ID dans cette crate ne signifie pas qu’un décodeur, exécuteur ou matérialisateur existe.
 
 ## API publique
 
-- les constantes `*_PROGRAM_ID` et `STAKE_CONFIG_ACCOUNT_ID` exposent les adresses Base58 canoniques ;
-- `ProgramIdEntry` conserve un code stable et une adresse, accessibles par les champs compatibles `name`/`address` et par `code()`/`program_id()` ;
-- `native_program_ids()` retourne exactement les 18 surfaces exécutables de Solana Core ;
-- `native_well_known_account_ids()` sépare les comptes natifs non exécutables ;
-- `registered_program_ids()` et son alias de compatibilité `entries()` retournent le registre actuellement migré ;
-- `find_registered_program_id()` effectue une recherche exacte par adresse.
+- constantes `*_PROGRAM_ID` ;
+- `STAKE_CONFIG_ACCOUNT_ID` et alias historique associé ;
+- `ProgramIdEntry` ;
+- `entries()` ;
+- `registered_program_ids()` ;
+- `native_program_ids()` ;
+- `native_well_known_account_ids()` ;
+- `find_registered_program_id()`.
 
-`STAKE_CONFIG_PROGRAM_ID` reste uniquement un alias de compatibilité historique. L’adresse correspondante est un compte de configuration Stake connu, pas un programme exécutable.
+## Sources documentaires
+
+La documentation détaillée des Program IDs, de leur vérification et des IDL sera construite séparément. Elle pourra utiliser les archives bot2 et d’autres projets historiques, mais le code de production reste fondé sur les constantes vérifiées de cette crate.
+
+## Documentation
+
+- [USAGE.md](USAGE.md)
+- [TODO.md](TODO.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [Matrice des surfaces](../docs/architecture/SURFACE_CRATE_MATRIX.md)

kb-program-ids/TODO.md

@@ -0,0 +1,12 @@
+<!-- file: kb-program-ids/TODO.md -->
+<!-- version: 1 -->
+
+# TODO — kb-program-ids
+
+- [ ] Documentation - produire le registre documentaire vérifié des Program IDs et de leurs sources.
+- [ ] Documentation - associer chaque IDL archivée à sa provenance vérifiée et à son Program ID.
+- [ ] Audit - rescanner les documents historiques bot2 avant de déclarer l’inventaire documentaire complet.
+- [ ] Audit - intégrer ultérieurement les sources d’un projet antérieur à bot2 lorsqu’elles seront fournies.
+- [ ] Vérification - confirmer la nature du programme `MAyhSmzXzV1pTf7LsNkrNwkWKTo4ougAJ1PPg47MD4e` avant classement.
+- [ ] Vérification - déterminer si `pumpup_ai` appartient à la famille Pump ou à un protocole distinct.
+- [ ] Tests - maintenir l’unicité, le tri et la séparation entre programmes exécutables et comptes connus.

kb-program-ids/USAGE.md

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