<!-- file: docs/PROGRAM_NAMING.md -->
<!-- version: 1 -->

# 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é

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

Le nom de crate correspondant est :

```text
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 :

```text
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 crates techniques déjà lisibles :

- `kb_decoder_solana_core` ;
- `kb_decoder_spl_token` ;
- `kb_decoder_spl_token_2022` ;
- `kb_decoder_spl_associated_token_account`.

Ces crates ne sont pas renommées en `kb_decoder_core_*` ou `kb_decoder_token_*`, car elles 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 une seule crate ;
3. mettre à jour `Cargo.toml` ;
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é :

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

Exemple refusé :

```text
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.