khadhroony-bot3/olddocs/archivekbot2/docs/EXECUTOR_SURFACE_MATRIX.md

Matrice des exécuteurs

Matrice canonique machine-readable — pre.022

Le fichier docs/NATIVE_SOLANA_EXECUTION_MATRIX.json est désormais la source vérifiable pour la clôture de l’exécuteur natif. Il contient exactement :

• 18 surfaces natives ;
• 14 surfaces callable ;
• 4 surfaces non_invocable ou historiques ;
• 109 opérations callable, chacune munie de sa source de construction, politique, préflight stateful, contrat de test, décision cluster et exposition UI.

Les quatre classifications sans builder client sont BPF Loader v1, BPF Loader v2, Native Loader et l’ancien ZK Token Proof historique. Un test Rust charge la matrice et la compare à SOLANA_CORE_OPERATION_CODES; toute omission, duplication ou opération inconnue fait échouer cargo test -p kb_executor_solana_core. Le validateur Python provisoire a été supprimé.

Le préflight stateful est actif pour Address Lookup Table, Config, Feature, Slashing et ZK ElGamal. Stake, Vote et Loaders restent marqués future dans la matrice pour leur preuve d’activation stateful approfondie ; cela ne retire aucun builder de la surface appelable, mais interdit toute exposition mutable sans validation cluster dédiée.

Cette matrice suit la symétrie entre surfaces de décodage et surfaces de construction d’instructions. Elle ne confond pas réservation d’une crate, disponibilité d’un builder, autorisation d’envoi et exposition dans une interface.

Socle d’exécution

Crate	Rôle
kb_execution_api	Contrats provider-neutral des capacités, politiques, plans et résultats.
kb_execution_safety	Garde-fous stateless avant simulation, signature ou envoi.
kb_execution_solana	Compilation Solana, blockhash/nonce, preuve de simulation et signature.
kb_rpc	Acquisition, simulation, envoi et confirmation JSON-RPC ; aucune clé privée.
kb_wallet	Résolution des signataires derrière un backend explicite.

Règle mécanique

Pour chaque décodeur de programme ou de protocole classifié :

kb_decoder_<surface> -> kb_executor_<surface>

Deux crates de décodage ne suivent volontairement pas cette règle :

• kb_decoder_api est le contrat commun des décodeurs, pas un programme appelable ;
• kb_decoder_anchor est un helper technique partagé, pas une surface on-chain autonome.

L’audit du workspace 0.4.2-pre.014 trouve :

104 crates kb_decoder_*
102 crates kb_executor_*
102 paires mécaniques exactes
2 exceptions techniques documentées
0 exécuteur orphelin

Répartition des 102 surfaces appariées

Famille	Paires
AMM	26
Launchpad	9
SPL	8
Lending	7
CLMM	6
Router	6
Vault	6
Bridge	4
Stable	4
Orderbook	3
Perpetuals	3
Staking	3
Admin	2
Fees	2
Adapter, CPMM, DLMM, Governance, Lock, Metadata, NFT, RWA, Solana Core, Treasury, Vesting, Wallet et Weighted	1 chacune

Niveaux de maturité

Une paire doit utiliser un statut explicite :

Statut	Signification
reserved	Crate et identité réservées ; aucun builder utilisable.
implementing	Contrat officiel et politiques en cours de validation.
complete	Toutes les opérations client officiellement appelables du périmètre sont construites et testées.
not_applicable	Surface non invocable, retirée ou purement technique, avec justification officielle.

Unsupported(reason) est acceptable pendant l’implémentation ou pour une impossibilité officielle précise. Il ne doit pas masquer une opération callable oubliée.

Politique de jalon

Chaque version qui active un décodeur doit également :

1. identifier la crate kb_executor_<surface> correspondante ;
2. attribuer un statut de maturité à l’exécuteur ;
3. lister les opérations client appelables et les opérations historiques decode-only ;
4. définir autorités, signataires, coûts, slippage ou autres garde-fous ;
5. comparer les payloads et comptes à un builder, une IDL ou un layout officiel ;
6. ajouter les tests offline puis localnet/devnet nécessaires ;
7. documenter l’API publique de la crate dans son README ;
8. décider séparément quelles opérations sont visibles dans kb_app_demo ou activables par une stratégie.

Une opération dangereuse peut rester hors UI, mais elle reste dans le périmètre de la bibliothèque lorsqu’elle est officiellement appelable.

Programme Solana Core

kb_executor_solana_core est la première surface passée de reserved à une implémentation opérationnelle. Après pre.021, elle expose toujours 109 opérations : 17 System, 4 Compute Budget, 5 Address Lookup Table, 6 précompiles de signature, 2 Config, 2 Feature, 2 Slashing, 3 ZK ElGamal, 24 Stake, 24 Vote, 11 Loader v3 et 9 Loader v4.

Surface native	Statut à la clôture 0.4.2	Décision
System, Compute Budget	complete pour les builders client actuels	orchestration durable nonce séparée ; exposition mutable toujours soumise aux politiques
Address Lookup Table	complete stateless	autorité, rent, capacité et cooldown contrôlés par le préflight stateful
Ed25519, secp256k1, secp256r1	complete	formes inline et offsets ; aucune autorisation métier implicite
Config	complete builder	wire local vérifié sans helper bincode; rent/état contrôlés avant envoi
Feature	complete builder	activation et révocation ; état/rent contrôlés avant envoi
Slashing	complete builder	close et plan atomique duplicate-block ; compte de preuve et fenêtres epoch stateful
ZK ElGamal Proof	complete builder	douze preuves inline/account et fermeture de contexte
ZK Token Proof historique	not_applicable	programme retiré/stub runtime, conservé uniquement pour décodage historique
Stake	complete pour les 24 helpers clients actuels	validations compte/rent/epoch exigées avant exposition ; Redelegate historique decode-only
Vote	complete pour les 20 variantes wire + 4 créations	validations account/rent/autorités/BLS/tour exigées avant exposition
Loader v3 upgradeable	complete pour 11 opérations client	interface officielle wincode; état, rent, owner et capacité restent stateful
Loader v4	complete pour 9 plans client	wire officiel reproduit sans activer les helpers bincode; état/autorité/rent restent stateful
BPF Loader v1/v2	historical_decode_only	builders dépréciés historiques non promus dans l’exécuteur moderne
Native Loader direct	non_invocable_by_client_instruction	déploiement lié au logiciel validator, aucun builder transactionnel inventé

pre.021 ne change aucune capacité : elle centralise les validations communes pub(crate) et élimine les implémentations identiques détectées dans les modules System, ALT, Config/Feature, Slashing, ZK, Stake, Vote et Loader.

La clôture 0.4.2 confirme la matrice machine-readable des dix-huit surfaces natives, avec pour chaque opération : builder/layout officiel, politique, tests offline, statut de validation cluster et décision d’exposition UI.

Versions futures

Le ROADMAP.md associe désormais explicitement les exécuteurs aux séries Pump, Meteora, Raydium, Orca, Jupiter/routeurs et à chaque jalon ultérieur de décodeur. La symétrie de crates ne vaut pas activation : les listeners et stratégies ne peuvent demander que des capacités explicitement validées et autorisées.