131 lines
11 KiB
Markdown
131 lines
11 KiB
Markdown
<!-- file: docs/EXECUTOR_SURFACE_MATRIX.md -->
|
||
<!-- version: 10 -->
|
||
|
||
# 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-lib::executor::solana::transaction` | Compilation Solana, blockhash/nonce, preuve de simulation et signature. |
|
||
| `kb_onchain_transport` | 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é :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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.
|