khadhroony-solana-project/deltas/0.1.1/pre.001-fix.002.md

Delta 0.1.1-pre.001-fix.002

Base requise

Livraison précédente appliquée et commitée :

0.1.1-pre.001-fix.001

Type de livraison

ksp-doc-0.1.1-pre.001-fix.002.zip

Objectif

Compléter le cadrage Program IDs de pre.001 avant ouverture de pre.002, après réaudit de l'ancien registre/IDLs bot3 et confrontation à des Program IDs publics actuels.

Ce correctif reste purement documentaire. Il fixe l'architecture de classification/recherche nécessaire pour que le registre KSP puisse ultérieurement retrouver les programmes par domaine, famille, protocole, sous-famille et génération sans dupliquer plusieurs registres statiques.

Version Cargo

Aucun fichier de code/build/runtime n'est modifié.

workspace.package.version reste donc :

0.1.1-pre.1

Identifiant de livraison/commit :

0.1.1-pre.001-fix.002

Fichiers ajoutés

• deltas/0.1.1/pre.001-fix.002.md

Fichiers modifiés

• docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md — version documentaire 2 -> 3.

Décisions acquises

Registre canonique unique

KSP ne doit pas maintenir des tableaux indépendants pour chaque vue (native, amm, protocole, etc.).

entries() reste la source canonique et les vues/recherches sont dérivées de la classification de chaque ProgramIdEntry.

Taxonomie minimale

ProgramIdEntry doit être conçu pour porter au minimum les axes descriptifs suivants :

domain
family
protocol
subfamily?
program_version?
kind

auxquels s'ajoutent le code KSP unique, la chaîne Base58 PRGID_* et le Pubkey PRGIDPK_*.

Les vocabulaires de classification restent extensibles. Core ne doit pas posséder une enum fermée de tous les protocoles/familles futurs.

AMM comme famille agrégatrice

Le réaudit de bot3 montre que les anciens préfixes AMM, CPMM, CLMM, DLMM, STABLE_SWAP et WEIGHTED_SWAP représentent plusieurs spécialisations d'une même grande famille utile pour la recherche.

La direction KSP devient donc :

family = amm

avec des subfamily optionnelles telles que :

cpmm
clmm
dlmm
damm
stable_swap
weighted_swap
gamma
ssl

lorsqu'elles correspondent réellement à une branche/architecture reconnue.

Une future amm_program_ids() doit filtrer le registre canonique sur cette famille et inclure toutes ces sous-familles.

subfamily et program_version sont deux axes indépendants

La version ne doit pas être détournée en sous-famille.

Cas audités :

• SPL Memo : trois Program IDs v1/v3/v4, même lignée fonctionnelle ;
• Aldrin AMM : v1/v2, même famille/protocole ;
• Meteora DAMM : sous-famille damm, versions v1/v2 ;
• Meteora DLMM : sous-famille dlmm distincte de DAMM ;
• Jupiter Aggregator : même lignée, versions v4/v6 ;
• GooseFX : GAMMA et SSL sont des branches distinctes ; SSL v2 possède une version, tandis qu'aucun v1 ne doit être inventé pour GAMMA.

Nom du champ de version

Le champ retenu conceptuellement est :

program_version

et non protocol_version.

Raison : un protocole peut posséder simultanément plusieurs programmes/composants dont les versions évoluent indépendamment. La version doit être attachée à la lignée du Program ID concerné, pas au protocole entier.

program_version est un label de génération reconnu (v1, v2, v4, v6, v0.5, etc.), pas nécessairement un SemVer.

Version d'IDL explicitement distincte

Une version d'IDL/schema n'est pas une version de Program ID.

Exemples observés dans les IDLs archivées bot3 :

• Jupiter V6 : IDL 0.1.0 ;
• GooseFX SSL V2 : IDL 0.3.0 ;
• GooseFX GAMMA : IDL/schema 0.2.0 ;
• Meteora DAMM V2 : IDL/schema distinct de la génération publique v2.

La provenance/version des IDLs appartiendra à la couche Interface/decoder lorsqu'elle sera ouverte ; elle n'entre pas dans ProgramIdEntry de Core en 0.1.1.

Nomenclature des constantes

La nomenclature Rust est séparée de la taxonomie fonctionnelle.

Le premier segment après PRGID_/PRGIDPK_ est désormais nommé NAMESPACE, afin de ne pas confondre le nom public stable avec le champ taxonomique domain :

PRGID_<NAMESPACE>_<PROGRAM_OR_FAMILY>_<VARIANT?>_<VERSION?>
PRGIDPK_<NAMESPACE>_<PROGRAM_OR_FAMILY>_<VARIANT?>_<VERSION?>

Exemples :

PRGID_SPL_MEMO_V3
PRGIDPK_SPL_MEMO_V3

PRGID_METEORA_DAMM_V2
PRGIDPK_METEORA_DAMM_V2

PRGID_GOOSEFX_GAMMA
PRGIDPK_GOOSEFX_GAMMA

PRGID_GOOSEFX_SSL_V2
PRGIDPK_GOOSEFX_SSL_V2

Le symbole public ne doit pas être renommé uniquement parce qu'une classification fonctionnelle est affinée plus tard.

Recherches et vues prévues

Direction conceptuelle :

ProgramIdEntry
ProgramIdFilter
entries()
program_ids(filter)
native_program_ids()
find_program_id()

Le filtre doit pouvoir combiner plusieurs critères.

Des helpers de recherche peuvent être proposés :

program_ids_by_domain(...)
program_ids_by_family(...)
program_ids_by_protocol(...)

native_program_ids() reste une vue Core réelle de 0.1.1.

amm_program_ids() est explicitement prévue pour la surface future possédant des IDs AMM, mais n'est pas créée vide pendant 0.1.1 puisque les AMM sont hors scope fonctionnel de la release.

Les vues doivent pouvoir être des iterators/views du registre canonique afin d'éviter la duplication de tableaux statiques.

Réaudit effectué

Archive bot3

Le réaudit a porté sur :

• ks-program-ids et ses 137 entrées historiques ;
• ProgramIdEntry, entries(), native_program_ids() et la recherche historique ;
• les familles historiques AMM/CLMM/CPMM/DLMM/router/orderbook/etc. ;
• les IDLs archivées, notamment GooseFX GAMMA/V2, Meteora DAMM/DLMM, Jupiter v4/v6, CCTP v1/v2, Raydium CLMM/CPMM, OpenBook v2 et Marginfi v2.

L'inventaire montre également qu'un même protocole traverse plusieurs familles : Jupiter, Raydium, Meteora, Kamino, MetaDAO, Pump, Metaplex, Orca, etc. protocol doit donc être un axe séparé de family.

Sources externes actuelles

Contrôles représentatifs effectués le 2026-08-14 :

• Agave runtime fetch-spl.sh : Memo 1.0.0, 3.0.0 et 4.0.0 sont associés à trois Program IDs distincts ;
• spl-memo-interface actuel : modules v1, v3, v4 distincts ;
• Solana Explorer et Solscan : présence/identification des Program IDs Memo et de programmes DEX audités ;
• GooseFX officiel : GAMMA est une lignée AMM distincte ; l'écosystème publie également la lignée SSL ;
• Meteora officiel : DAMM v1, DAMM v2 et DLMM sont des surfaces distinctes ;
• Jupiter officiel : plusieurs générations du Swap Aggregator sont distinguées par Program ID.

Ces contrôles sont utilisés comme validation de taxonomie, pas comme dépendances KSP.

Impact sur pre.003

pre.003 devra désormais :

• implémenter ProgramIdEntry avec une taxonomie compatible avec les axes acquis ;
• implémenter ProgramIdFilter ou une forme équivalente permettant les intersections ;
• dériver native_program_ids() du registre canonique ;
• tester les filtres par domaine/famille/protocole/sous-famille/version/kind ;
• ne jamais confondre génération du programme et version d'IDL ;
• préserver la possibilité d'ajouter plus tard amm_program_ids() sans modifier la structure fondamentale du registre.

Hors scope inchangé

Ce correctif n'ajoute aucun Program ID SPL/DEX au code de 0.1.1 et n'ouvre toujours pas :

• Logging ;
• Config ;
• Tauri ;
• Wallet/signing ;
• codecs wire ;
• Interface/IDL runtime ;
• Program decoding/dispatch ;
• execution ;
• Transport ;
• Store ;
• Materializer ;
• workers/jobs/pipelines ;
• scenarios ;
• trading/ML.

Validations exécutées

• réaudit du registre ks-program-ids de l'archive bot3 ;
• inventaire des Program IDs versionnés et des protocoles présents dans plusieurs familles ;
• inspection ciblée des IDLs multi-version/à plusieurs sous-familles ;
• confrontation représentative avec Agave/SPL, Solana Explorer, Solscan, GooseFX, Meteora et Jupiter ;
• relecture du plan après modification ;
• contrôle statique des headers/version documentaire ;
• contrôle des fins de fichiers ;
• contrôle de l'absence de modification Cargo/code/runtime dans ce fix.

Validations non exécutées

Aucune validation Cargo n'est requise pour ce fix exclusivement documentaire et aucune n'est déclarée réussie.

Suite

Après application et commit de ce correctif, le cadrage pre.001 peut être considéré comme clôturé et la session peut passer à :

0.1.1-pre.002 — Error/Result et fondation API