khadhroony-bot3/docs/PROGRAM_NAMING.md

Nommage canonique des programmes et surfaces

Le nommage doit permettre de distinguer la fonction réelle du programme, sa famille protocolaire et sa version.

Format recommandé

<function_code>_<family_code>_<identifier_code>[_vN]

Le nom de crate correspondant est :

kb_decoder_<function_code>_<family_code>_<identifier_code>[_vN]

Préfixes fonctionnels autorisés

Le préfixe doit décrire la fonction principale du programme, pas seulement le fait qu'il s'agit d'un programme Solana.

Exemples de préfixes acceptés :

core
token
amm
cpmm
clmm
dlmm
stable_swap
weighted_swap
orderbook
router
launchpad
lending
vault
staking
bridge
perpetuals
oracle
nft
metadata
admin
fees
governance
treasury
lock
vesting
unknown

Le préfixe program est interdit pour les nouveaux noms canoniques. Une entrée non classifiée doit utiliser unknown_* et ne doit pas déclencher la création d'une crate cible avant classification.

Cas Meteora DAMM

damm est conservé comme identifiant de surface Meteora, mais pas comme préfixe fonctionnel. La forme attendue est donc amm_meteora_damm_v1 ou amm_meteora_damm_v2. En revanche cpmm, clmm, dlmm, stable_swap et weighted_swap sont des mécanismes et peuvent être utilisés comme préfixes fonctionnels.

Colonnes à conserver

Le registre ne doit pas perdre les anciens noms. Chaque programme doit conserver :

• program_id : adresse Solana réelle ;
• source_code : nom brut issu de la liste, d’un IDL ou d’une ancienne documentation ;
• normalized_code : nom nettoyé sans faute évidente ;
• canonical_surface_code : nom cible stable ;
• current_crate : crate existant si la surface est déjà réservée ;
• target_crate : nom de crate à atteindre après migration contrôlée ;
• registry_status : statut de contrôle.

Exemples de normalisation

Nom source	Fonction	Famille	Nom canonique
raydium_lp_v4	amm	raydium	amm_raydium_lp_v4
raydium_cpmm	cpmm	raydium	cpmm_raydium
raydium_clmm	clmm	raydium	clmm_raydium
meteora_dlmm	dlmm	meteora	dlmm_meteora
meteora_damm_v2	amm	meteora	amm_meteora_damm_v2
jupiter_agregator_v6	router	jupiter	router_jupiter_aggregator_v6
okx_labs_v2	router	okx	router_okx_labs_v2
openbook_v2	orderbook	openbook	orderbook_openbook_v2
phoenix	orderbook	phoenix	orderbook_phoenix_v1
pump_swap	amm	pump	amm_pump_swap
pump_fun	launchpad	pump	launchpad_pump_fun
pump_fees	admin	pump	admin_pump_fees
orca_whirlpool	clmm	orca	clmm_orca_whirlpool
metaplex_token_metadata	metadata	metaplex	metadata_metaplex_token_metadata
bubblegum	nft	metaplex	nft_metaplex_bubblegum

Exceptions conservées

Les programmes Solana/SPL de base restent groupés dans des modules techniques privés et des types publics explicites :

• DcSolanaCoreDecoder ;
• DcSplTokenDecoder ;
• DcSplToken2022Decoder ;
• DcSplAssociatedTokenAccountDecoder.

Ces types restent dans la façade kb_lib, car ils servent de couche primitive avant les surfaces DEX/router.

Politique de migration

La migration physique des dossiers ne doit pas être faite en masse. Pour chaque rename :

1. prouver que le program_id correspond à la surface ;
2. créer ou renommer un seul module privé ;
3. mettre à jour la façade kb-lib/src/lib.rs ;
4. mettre à jour le registre ;
5. exécuter cargo build ;
6. supprimer l’ancien alias seulement après validation.

Préfixe hexadécimal

Les préfixes 00 à ff sont interdits comme préfixes principaux de crate. Ils peuvent exister uniquement comme champ de registre optionnel registry_code. Le nom canonique doit rester lisible et fonctionnel.

Exemple accepté :

registry_code = "01"
canonical_surface_code = "amm_pump_swap"
target_crate = "kb_decoder_amm_pump_swap"

Exemple refusé :

kb_decoder_01_pump_swap

Fichiers constants.rs

Les crates peuvent avoir un fichier src/constants.rs pour regrouper les program_id, discriminants, sélecteurs, longueurs Borsh et autres constantes techniques. Les program_id publics sont réexportés dans lib.rs. Les constantes internes futures, par exemple des discriminants ou tailles de payload, doivent rester pub(crate) sauf besoin explicite d'API publique.

Depuis un module interne de la même crate, une constante réexportée par lib.rs doit être appelée via crate::CONSTANT_NAME. Le chemin crate::constants::CONSTANT_NAME reste réservé aux constantes non réexportées.

Préfixes ajoutés après inspection IDL

• adapter : wrapper technique ou adaptation de format, par exemple adapter_saber_decimal_wrapper.
• rwa : programme d'actifs réels tokenisés ou marchés globaux, par exemple rwa_ondo_global_markets.
• vesting : programme de vesting, streaming ou timelock.
• wallet : smart wallet applicatif ou surface d'approbation/exécution.

Préfixe fees

Le préfixe fees est autorisé pour les programmes dont le rôle principal est la configuration, distribution ou réclamation de frais. Il doit être préféré à admin lorsque la surface est explicitement centrée sur le partage de frais.