0.1.0
This commit is contained in:
152
docs/PROGRAM_NAMING.md
Normal file
152
docs/PROGRAM_NAMING.md
Normal file
@@ -0,0 +1,152 @@
|
||||
<!-- 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.
|
||||
Reference in New Issue
Block a user