v0.1.0-pre.011
This commit is contained in:
@@ -35,7 +35,7 @@ Validation du jalon de cadrage stockage : conventions PostgreSQL définies autou
|
||||
|
||||
## 0.2.1 — contrats `kb_store_core` et replay instruction-level
|
||||
|
||||
Validation du jalon de contrats storage : `kb_store_core` expose les types communs backend-agnostiques pour pagination, healthcheck, migrations, erreurs de stockage, DTOs applicatifs, entities proches SQL et traits repositories sans implémentation PostgreSQL. Les contrats couvrent le raw RPC et WebSocket, le cycle de vie raw `Full` / `Compacted` / `Archived` / `Purged`, les états de traitement raw, la signature optionnelle des notifications WebSocket, la déduplication par `notification_key`, le lien futur optionnel notification vers transaction canonique, ainsi que le replay par instruction. Le replay est défini comme un scheduling au niveau instruction, mais le décodage reçoit un contexte extrait complet via `CoreInstructionReplayInput` : instruction ciblée, account keys, logs, balance changes et contexte transactionnel minimal. Les repositories restent abstraits et ne créent encore ni pool PostgreSQL, ni migration SQL réelle. Validation locale effectuée : `cargo test -p kb_store_core` avec 28 tests passés et `cargo clippy --all-targets` sans avertissement. Les validations précédentes du jalon ont également confirmé `kb_store_pg` sans test actif, `kb_config` avec 35 tests passés et `kb_app_demo` avec 28 tests passés.
|
||||
Validation du jalon de contrats storage : `kb_store_core` expose les types communs backend-agnostiques pour pagination, healthcheck, migrations, erreurs de stockage, DTOs applicatifs, entities proches SQL et traits repositories sans implémentation PostgreSQL. Les contrats couvrent le raw RPC et WebSocket, le cycle de vie raw `Full` / `Compacted` / `Archived` / `Purged`, les états de traitement raw, la signature optionnelle des notifications WebSocket, la déduplication par `notification_key`, le lien futur optionnel notification vers transaction canonique, ainsi que le replay par instruction. Le replay est défini comme un scheduling au niveau instruction, mais le décodage reçoit un contexte extrait complet via `MdCoreInstructionReplayInput` : instruction ciblée, account keys, logs, balance changes et contexte transactionnel minimal. Les repositories restent abstraits et ne créent encore ni pool PostgreSQL, ni migration SQL réelle. Validation locale effectuée : `cargo test -p kb_store_core` avec 28 tests passés et `cargo clippy --all-targets` sans avertissement. Les validations précédentes du jalon ont également confirmé `kb_store_pg` sans test actif, `kb_config` avec 35 tests passés et `kb_app_demo` avec 28 tests passés.
|
||||
|
||||
## 0.2.2 — infrastructure PostgreSQL minimale
|
||||
|
||||
@@ -47,7 +47,7 @@ Validation du jalon raw store minimal : `kb_store_pg` crée et initialise les de
|
||||
|
||||
## 0.2.4 — core Solana normalisé minimal
|
||||
|
||||
Validation du jalon core store minimal : `kb_store_pg` crée et initialise maintenant les tables core `kb_sol_core_transactions`, `kb_sol_core_account_keys`, `kb_sol_core_instructions`, `kb_sol_core_inner_instructions`, `kb_sol_core_logs` et `kb_sol_core_balance_changes`, en complément du raw store `0.2.3`, sans schema PostgreSQL applicatif explicite. Les migrations et l'initializer utilisent des noms SQL préfixés et explicites pour les contraintes et index : `pk_`, `fk_`, `ck_`, `ux_` et `ix_`. L'initialisation raw/core est sérialisée par un verrou PostgreSQL `pg_advisory_xact_lock` afin d'éviter les courses concurrentes pendant les tests ou les démarrages parallèles. `CoreTransactionStore` dispose de l'implémentation PostgreSQL minimale pour insérer les transactions core, account keys, instructions, inner instructions, logs et deltas de balances, puis reconstruire `CoreInstructionReplayInput` pour les futurs décodeurs. Le script de maintenance `kb_store_pg/maintenance/drop_raw_core_store.sql` permet de réinitialiser explicitement les tables raw/core locales dans l'ordre inverse des dépendances. Validation locale effectuée : `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana cargo test -p kb_store_pg -- --nocapture` avec 30 tests passés, création vérifiée des 8 tables dans PostgreSQL, réinitialisation validée via le script de maintenance, puis `cargo clippy --all-targets` sans avertissement. Le worker d'extraction raw RPC vers core, les observations et le ledger ops sont conservés pour les jalons suivants.
|
||||
Validation du jalon core store minimal : `kb_store_pg` crée et initialise maintenant les tables core `kb_sol_core_transactions`, `kb_sol_core_account_keys`, `kb_sol_core_instructions`, `kb_sol_core_inner_instructions`, `kb_sol_core_logs` et `kb_sol_core_balance_changes`, en complément du raw store `0.2.3`, sans schema PostgreSQL applicatif explicite. Les migrations et l'initializer utilisent des noms SQL préfixés et explicites pour les contraintes et index : `pk_`, `fk_`, `ck_`, `ux_` et `ix_`. L'initialisation raw/core est sérialisée par un verrou PostgreSQL `pg_advisory_xact_lock` afin d'éviter les courses concurrentes pendant les tests ou les démarrages parallèles. `CoreTransactionStore` dispose de l'implémentation PostgreSQL minimale pour insérer les transactions core, account keys, instructions, inner instructions, logs et deltas de balances, puis reconstruire `MdCoreInstructionReplayInput` pour les futurs décodeurs. Le script de maintenance `kb_store_pg/maintenance/drop_raw_core_store.sql` permet de réinitialiser explicitement les tables raw/core locales dans l'ordre inverse des dépendances. Validation locale effectuée : `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana cargo test -p kb_store_pg -- --nocapture` avec 30 tests passés, création vérifiée des 8 tables dans PostgreSQL, réinitialisation validée via le script de maintenance, puis `cargo clippy --all-targets` sans avertissement. Le worker d'extraction raw RPC vers core, les observations et le ledger ops sont conservés pour les jalons suivants.
|
||||
|
||||
## 0.2.5 — diagnostics SQL PostgreSQL dans `kb_app_demo`
|
||||
|
||||
|
||||
@@ -172,7 +172,7 @@ Ce fichier contient les changements futurs et le phasage prévu. Il ne remplace
|
||||
- [x] Ajouter les types communs : pagination, tri, limites, healthcheck, statut migration.
|
||||
- [x] Ajouter les premiers DTO génériques : raw RPC transaction, raw WS notification, core transaction, core instruction.
|
||||
- [x] Ajouter les contrats core pour account keys, logs et balance changes extraits.
|
||||
- [x] Ajouter `CoreInstructionReplayInput` pour fournir aux décodeurs une instruction avec contexte extrait.
|
||||
- [x] Ajouter `MdCoreInstructionReplayInput` pour fournir aux décodeurs une instruction avec contexte extrait.
|
||||
- [x] Ajouter les contrats de cycle de vie raw : état de rétention, état de traitement et mark lifecycle.
|
||||
- [x] Ajouter les contrats de replay par instruction : état instruction, filtre de replay et lifecycle mark.
|
||||
- [x] Ajouter les premiers traits repository sans implémentation SQL.
|
||||
@@ -229,7 +229,7 @@ Ce fichier contient les changements futurs et le phasage prévu. Il ne remplace
|
||||
### 0.2.4 — core Solana normalisé minimal
|
||||
|
||||
- [x] Créer les tables core minimales : `kb_sol_core_transactions`, `kb_sol_core_account_keys`, `kb_sol_core_instructions`, `kb_sol_core_inner_instructions`, `kb_sol_core_logs`, `kb_sol_core_balance_changes`.
|
||||
- [x] Construire `CoreInstructionReplayInput` depuis les tables `core` pour les décodeurs.
|
||||
- [x] Construire `MdCoreInstructionReplayInput` depuis les tables `core` pour les décodeurs.
|
||||
- [x] Marquer les instructions insérées comme `Pending` pour permettre un replay instruction-level.
|
||||
- [x] Préparer le replay partiel par état, slot et program id via `CoreInstructionReplayFilter`.
|
||||
- [x] Ajouter une initialisation idempotente raw/core via `PostgresStore::initialize_store_schema()`.
|
||||
@@ -460,7 +460,7 @@ Les contrôles autrefois prévus dans `0.3.5` sont reclassés ainsi : la stabili
|
||||
- [x] Auditer les crates utilisant `tracing.workspace = true` et couvrir les treize crates alors actives par un test de constante canonique et par les routes des trois profils.
|
||||
- [x] Ajouter le tracing propriétaire manquant sur les clients/pools HTTP et WebSocket ainsi que sur le backfill ; promouvoir les inputs decode unmatched, statuts failed/unsupported et échecs de matérialisation/persistance au niveau `error`.
|
||||
- [x] Formaliser dans `docs/SOLANA_INTERFACE_DEPENDENCIES.md` la politique d’interfaces officielles : dépendance seulement au point de consommation, priorité `wincode` puis Borsh, parser borné lorsque l’interface n’expose que `bincode`.
|
||||
- [x] Passer `CoreInstructionReplayInput` au contrat `2` avec une liste stable et numériquement ordonnée des instructions outer, sans migration SQL, afin de résoudre les références inter-instructions des précompiles.
|
||||
- [x] Passer `MdCoreInstructionReplayInput` au contrat `2` avec une liste stable et numériquement ordonnée des instructions outer, sans migration SQL, afin de résoudre les références inter-instructions des précompiles.
|
||||
- [x] Décoder `zk_elgamal_proof` dans `pre.015` selon `solana-zk-elgamal-proof-interface ^0.1` et le runtime Agave : treize discriminants, preuves inline ou référencées par compte, contexte optionnel et fermeture du contexte, sans recalcul cryptographique.
|
||||
- [x] Décoder dans `pre.016` l’ancien `zk_token_proof` comme compatibilité historique, puis retirer dans `pre.019` la dépendance dépréciée `solana-zk-token-sdk` au profit d’un miroir wire local borné des dix-sept discriminants et tailles auditées.
|
||||
- [x] Décoder les loaders `native_loader`, `bpf_loader_deprecated`, `bpf_loader`, `bpf_loader_upgradeable` et `loader_v4` ; classer l’invocation Native Loader opaque comme `ignored` sans sémantique inventée.
|
||||
@@ -532,14 +532,14 @@ Les contrôles autrefois prévus dans `0.3.5` sont reclassés ainsi : la stabili
|
||||
|
||||
#### Suite d’orchestration
|
||||
|
||||
- [x] `pre.004` : ajouter dans `kb_rpc` les adaptateurs typés `getGenesisHash`, `getLatestBlockhash`, `getFeeForMessage` et `simulateTransaction`, avec routage par rôle, classification des clusters publics, diagnostics runtime et conversion vers `ExecutionSimulationResult`, sans signature ni envoi.
|
||||
- [x] `pre.004` : ajouter dans `kb_rpc` les adaptateurs typés `getGenesisHash`, `getLatestBlockhash`, `getFeeForMessage` et `simulateTransaction`, avec routage par rôle, classification des clusters publics, diagnostics runtime et conversion vers `ExApiExecutionSimulationResult`, sans signature ni envoi.
|
||||
- [x] `pre.004` : documenter dans `kb_executor_solana_core/README.md` chaque fonction publique, les six opérations constructibles, leurs paramètres, résultats, effets et frontières.
|
||||
- [x] Valider localement `pre.004` : `kb_rpc` 63 tests, `kb_execution_api` 21 tests, `kb_execution_safety` 13 tests, `kb_executor_solana_core` 10 tests, `kb_config` 40 tests et Clippy global propre.
|
||||
- [x] `pre.005` : ajouter `kb_execution_solana` pour assembler les instructions planifiées en transaction legacy, produire les payloads base64 de frais/simulation, lier la simulation au hash exact du message, résoudre exactement les signataires requis via l’interface Solana `Signer` et signer séparément hors Tauri.
|
||||
- [x] `pre.005` : renommer la constante interne en `MAINNET_GENESIS_HASH` sans changer sa valeur ; conserver `mainnet-beta` seulement comme alias historique des endpoints/CLI et renommer le variant public en `Mainnet` sérialisé `mainnet`.
|
||||
- [x] `pre.005` : distinguer la simulation exacte de la simulation avec remplacement de blockhash et interdire qu’un résultat `replaceRecentBlockhash=true` autorise la signature du message original.
|
||||
- [x] Valider localement les tests ciblés de `pre.005`/`pre.006` : `kb_execution_solana` 7 tests, `kb_execution_api` 22 tests, `kb_execution_safety` 15 tests, `kb_rpc` 63 tests, `kb_executor_solana_core` 10 tests, `kb_wallet` 6 tests et `kb_config` 40 tests.
|
||||
- [x] `pre.006` : corriger la compilation croisée de `pre.005`, supprimer l’avertissement TS-rs sur l’alias historique `mainnet_beta`, utiliser le trait public `TypedInstructionExecutor` dans les tests d’assemblage, resynchroniser le contrat de simulation RPC et rendre les erreurs de routage tracing explicites.
|
||||
- [x] `pre.006` : corriger la compilation croisée de `pre.005`, supprimer l’avertissement TS-rs sur l’alias historique `mainnet_beta`, utiliser le trait public `ExApiTypedInstructionExecutor` dans les tests d’assemblage, resynchroniser le contrat de simulation RPC et rendre les erreurs de routage tracing explicites.
|
||||
- [x] `pre.007` : supprimer le dernier opérateur `?` introduit dans un chemin de production de `kb_execution_api`, le remplacer par un `match` avec propagation explicite et auditer les fichiers d’exécution `0.4.2` contre `?`, `unwrap` et `expect` de production.
|
||||
- [x] Valider localement `pre.007` : `kb_execution_api` 22 tests et Clippy global propre.
|
||||
- [x] `pre.008` : ajouter les contrats RPC typés `getBalance`, `requestAirdrop`, `sendTransaction`, `getSignatureStatuses` et `getBlockHeight`, avec routage par rôle, préflight obligatoire, contrôle de la signature retournée et confirmation bornée jusqu’à succès, échec, expiration ou timeout.
|
||||
@@ -603,7 +603,7 @@ Les contrôles autrefois prévus dans `0.3.5` sont reclassés ainsi : la stabili
|
||||
- [x] Valider localement `pre.019` : `kb_executor_solana_core` 70 tests, `kb_execution_api` 22, `kb_execution_safety` 15, `kb_execution_solana` 12, `kb_rpc` 70 et Clippy global propre.
|
||||
- [x] `pre.020` : onze opérations Loader v3 et neuf opérations Loader v4 réellement constructibles, avec déploiement/upgrade/autorités/fermeture hors UI; BPF Loader v1/v2 restent historiques `decode-only` et Native Loader est classé sans instruction client.
|
||||
- [x] Valider localement `pre.020` : `kb_executor_solana_core` 81 tests, `kb_decoder_solana_core` 115, `kb_execution_api` 22, `kb_execution_safety` 15, `kb_execution_solana` 12 et `kb_rpc` 70.
|
||||
- [x] `pre.021` : centraliser dans un module privé les parsers `Pubkey`/program ID et les validations communes de longueur, montant positif, comptes distincts, dérivation seedée et erreurs partagées ; supprimer les implémentations de production identiques sans modifier les 109 opérations ni leur wire.
|
||||
- [x] `pre.021` : centraliser dans un module privé les parsers `MdPubkey`/program ID et les validations communes de longueur, montant positif, comptes distincts, dérivation seedée et erreurs partagées ; supprimer les implémentations de production identiques sans modifier les 109 opérations ni leur wire.
|
||||
- [x] Valider localement `pre.021` après `fix.001` : `kb_executor_solana_core` 86 tests et `cargo clippy --all-targets` propre ; ce Clippy couvre également les changements Loader de `pre.020`.
|
||||
- [x] `pre.022` : implémenter le préflight stateful Localnet/Devnet pour ALT, Config, Feature, Slashing et contextes ZK ElGamal ; ajouter `getEpochInfo` typé et la matrice machine-readable complète des 18 surfaces natives avec classification de toute opération non invocable.
|
||||
- [x] Valider localement `pre.022` : `kb_executor_solana_core` 87 tests, `kb_pipeline` 56 tests, `kb_rpc` 71 tests, `kb_execution_api` 22 tests, `kb_execution_safety` 15 tests, `kb_execution_solana` 12 tests, validateur de matrice réussi et `cargo clippy --all-targets` propre.
|
||||
|
||||
@@ -138,7 +138,7 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
|
||||
|
||||
- Une crate est opérationnelle lorsqu’elle effectue des I/O, orchestre un pipeline, décode, matérialise, exécute, applique une politique runtime ou prend une décision mutable observable.
|
||||
- Toute crate opérationnelle ajoutée ou modifiée doit dépendre de `tracing` depuis le workspace et déclarer exactement un `pub(crate) const TRACING_TARGET` dans `src/constants.rs`.
|
||||
- La valeur canonique de `TRACING_TARGET` est le nom exact du package Cargo. Les targets historiques `khbot.*`, les suffixes de module et les targets de fenêtre sont interdits dans les nouvelles modifications.
|
||||
- La valeur canonique de `DC_METADATA_MTM_TRACING_TARGET` est le nom exact du package Cargo. Les targets historiques `khbot.*`, les suffixes de module et les targets de fenêtre sont interdits dans les nouvelles modifications.
|
||||
- Les macros `tracing` doivent utiliser `target: crate::TRACING_TARGET` et des champs structurés stables. La granularité interne passe par `action`, `stage`, `window`, `campaign_id`, `signature`, `instruction_path`, `program_id`, `processor_name`, `processor_version`, `status` et `error_code`.
|
||||
- Les crates passives de types, contrats, DTO, API sans exécution, registres ou constantes restent sans dépendance `tracing`. `kb_config` reste une exception de bootstrap tant que sa validation précède l’installation du subscriber.
|
||||
- Il est interdit d’ajouter `tracing` sans événement réel ou de conserver un faux target uniquement consommé par `let _target`.
|
||||
@@ -150,14 +150,14 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
|
||||
- Chaque profil doit router les événements vers les sorties globales `debug.log`, `info.log`, `error.jsonl` et `app.log`, puis vers `debug.log`, `info.log` et `error.jsonl` dans un répertoire propre à chaque crate utilisant `tracing`.
|
||||
- L’ajout ou la suppression de `tracing.workspace = true` dans une crate impose la mise à jour simultanée de la matrice de routes, de ses tests et de `docs/TRACING_CONTRACT.md`.
|
||||
- Le contrat détaillé est défini dans `docs/TRACING_CONTRACT.md`.
|
||||
- L’audit mécanique spécifique au projet est exécuté par `python3 scripts/audit_khadhroony_workspace_rules.py`. Il couvre notamment `TRACING_TARGET` et l’usage obligatoire de `solana_pubkey::Pubkey` à la place de `solana_address::Address`.
|
||||
- L’audit mécanique spécifique au projet est exécuté par `python3 scripts/audit_khadhroony_workspace_rules.py`. Il couvre notamment `DC_METADATA_MTM_TRACING_TARGET` et l’usage obligatoire de `solana_pubkey::Pubkey` à la place de `solana_address::Address`.
|
||||
|
||||
## Règles de réutilisation des interfaces Solana et SPL
|
||||
|
||||
- Les dépendances déclarées dans `[workspace.dependencies]` forment un catalogue de versions et de features autorisées ; elles ne doivent être ajoutées à une crate consommatrice que lorsqu’un type, un encodeur, un décodeur ou un identifiant officiel est réellement utilisé.
|
||||
|
||||
- Dans un `Cargo.toml`, placer dans `[dependencies]` toute crate référencée par le code de bibliothèque compilé en production. Réserver `[dev-dependencies]` aux références contenues exclusivement dans `#[cfg(test)]`, les tests d’intégration, benches ou exemples. Une dépendance de test vers un décodeur ou matérialiseur concret est légitime lorsqu’elle sert uniquement à éprouver une orchestration générique fondée sur les traits API ; elle ne prouve pas qu’une capacité de production manque. Toute promotion de `dev-dependencies` vers `dependencies` doit être motivée par un appel runtime réel, et toute dépendance runtime inutilisée doit être supprimée.
|
||||
- Les registres de composition runtime des applications doivent énumérer explicitement chaque décodeur et matérialiseur concret activé. Toute nouvelle surface instructionnelle dotée d’un `EventMaterializer` doit être ajoutée au registre applicatif et couverte par un test d’inventaire ordonné ; une crate présente dans le workspace ou dans `kb_pipeline` n’est pas activée automatiquement. Les matérialiseurs exclusivement stateful qui n’implémentent pas `EventMaterializer` restent routés par leurs APIs de snapshots dédiées.
|
||||
- Les registres de composition runtime des applications doivent énumérer explicitement chaque décodeur et matérialiseur concret activé. Toute nouvelle surface instructionnelle dotée d’un `MtApiEventMaterializer` doit être ajoutée au registre applicatif et couverte par un test d’inventaire ordonné ; une crate présente dans le workspace ou dans `kb_pipeline` n’est pas activée automatiquement. Les matérialiseurs exclusivement stateful qui n’implémentent pas `MtApiEventMaterializer` restent routés par leurs APIs de snapshots dédiées.
|
||||
- Les corrélations instruction/état doivent produire une issue explicite (`confirmed`, `contradicted` ou `not_applicable`) et ne doivent jamais transformer automatiquement une configuration observée en violation, score ou conclusion métier.
|
||||
- Une interface officielle Solana ou SPL étroite doit être préférée à `solana-sdk` lorsque son contrat suffit.
|
||||
- L’ordre de préférence des formats est : schéma officiel `wincode`, schéma officiel Borsh, puis parseur local borné reproduisant exactement le runtime lorsque l’interface officielle n’expose que `bincode`.
|
||||
|
||||
@@ -38,8 +38,8 @@ L’extraction refuse explicitement :
|
||||
|
||||
- un `canonical_json` absent ;
|
||||
- un `canonical_json_hash` absent ;
|
||||
- une version différente de `CANONICAL_TRANSACTION_FORMAT_VERSION` ;
|
||||
- un JSON non désérialisable en `CanonicalTransaction` ;
|
||||
- une version différente de `MD_CANONICAL_TRANSACTION_FORMAT_VERSION` ;
|
||||
- un JSON non désérialisable en `MdCanonicalTransaction` ;
|
||||
- une signature ou un slot différent de la ligne raw ;
|
||||
- un hash recalculé différent du hash stocké ;
|
||||
- un indice de programme ou de compte hors de l’espace résolu.
|
||||
|
||||
@@ -58,6 +58,6 @@ Ce fichier sépare les identifiants primitifs Solana/SPL du registre des surface
|
||||
| `core_spl_single_pool_v1` | `SVSPxpvHdN29nkVg9rPapPNDddN5DipNLRUFhyjFThE` | `spl_single_pool` | `program` | `kb_decoder_spl_single_pool` | `core_specialized_reserved_current` |
|
||||
| `core_spl_name_service_v1` | `namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX` | `spl_name_service` | `program` | `kb_decoder_metadata_spl_name_service` | `core_specialized_reserved_current` |
|
||||
| `core_spl_stake_pool_v1` | `SPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHy` | `stake_pool` | `program` | `kb_decoder_spl_stake_pool` | `core_specialized_reserved_current` |
|
||||
| `core_spl_token_2022_v2022` | `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` | `token_2022` | `program` | `kb_decoder_spl_token_2022` | `core_handled` |
|
||||
| `core_spl_token_2022_v2022` | `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` | `token2022` | `program` | `kb_decoder_spl_token_2022` | `core_handled` |
|
||||
| `core_spl_token_2022_elgamal_registry_v1` | `regVYJW7tcT8zipN5YiBvHsvR5jXW1uLFxaHSbugABg` | `spl_token_2022_elgamal_registry` | `program` | `kb_decoder_spl_token_2022` | `core_specialized_reserved_current` |
|
||||
| `core_spl_token_v1` | `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` | `token` | `program` | `kb_decoder_spl_token` | `core_handled` |
|
||||
|
||||
@@ -20,7 +20,7 @@ core instruction contextualisée
|
||||
|
||||
## Input contextualisé
|
||||
|
||||
`CoreInstructionReplayInput` reste l’unique contrat d’entrée commun. Son contrat passe à la version `2` dans `0.4.1-pre.014`. Il contient la signature, le slot, le statut et l’erreur on-chain, le chemin stable de l’instruction, le program ID, les comptes résolus dans leur ordre original, le payload brut déterministe et son hash, toutes les instructions outer ordonnées par index numérique, les inner instructions descendantes, les logs reliés prudemment, les changements de balances et la version du contrat core.
|
||||
`MdCoreInstructionReplayInput` reste l’unique contrat d’entrée commun. Son contrat passe à la version `2` dans `0.4.1-pre.014`. Il contient la signature, le slot, le statut et l’erreur on-chain, le chemin stable de l’instruction, le program ID, les comptes résolus dans leur ordre original, le payload brut déterministe et son hash, toutes les instructions outer ordonnées par index numérique, les inner instructions descendantes, les logs reliés prudemment, les changements de balances et la version du contrat core.
|
||||
|
||||
`outer_instructions_json` est un tableau stable dont chaque entrée contient `instructionIndex`, `instructionPath`, `programId`, `payloadJson` et `payloadHash`. L’instruction cible est incluse. Cette projection provient des tables core existantes et ne nécessite aucune migration SQL.
|
||||
|
||||
@@ -30,7 +30,7 @@ Le passage au contrat `2` modifie légitimement les hashes existants, car les pa
|
||||
|
||||
## Contrat de décodeur
|
||||
|
||||
`InstructionDecoder` expose :
|
||||
`DcApiInstructionDecoder` expose :
|
||||
|
||||
- une identité stable `name/version` ;
|
||||
- les programmes et surfaces supportés ;
|
||||
@@ -58,7 +58,7 @@ observation_committed
|
||||
|
||||
`observation_committed` doit être faux lorsque la transaction a été annulée. Ces observations peuvent décrire une instruction tentée, un événement loggé avant l’erreur, une classification d’échec, une consommation de compute ou une surface appelée.
|
||||
|
||||
Elles ne peuvent pas produire automatiquement un trade réussi, une modification de liquidité réussie, un changement confirmé de catalogue ou une candle normale. `EventMaterializer` applique une politique explicite par famille. Les familles `trade`, `liquidity` et `lifecycle` sont refusées avant l’appel au matérialiseur lorsque la source est échouée ou non commitée. Une seconde barrière valide ensuite les familles de sortie et n’autorise, dans ce contexte, que les matérialisations d’audit ou de risque.
|
||||
Elles ne peuvent pas produire automatiquement un trade réussi, une modification de liquidité réussie, un changement confirmé de catalogue ou une candle normale. `MtApiEventMaterializer` applique une politique explicite par famille. Les familles `trade`, `liquidity` et `lifecycle` sont refusées avant l’appel au matérialiseur lorsque la source est échouée ou non commitée. Une seconde barrière valide ensuite les familles de sortie et n’autorise, dans ce contexte, que les matérialisations d’audit ou de risque.
|
||||
|
||||
## Persistance
|
||||
|
||||
|
||||
@@ -77,11 +77,11 @@ Le genesis hash sert à classifier les clusters publics connus. Le réseau de pr
|
||||
|
||||
La simulation accepte une transaction base64 non signée lorsque `sigVerify = false`; `replaceRecentBlockhash = true` permet au nœud de remplacer le blockhash avant simulation. Les erreurs runtime restent un résultat de simulation typé et ne sont pas confondues avec une erreur HTTP ou JSON-RPC.
|
||||
|
||||
`kb_rpc` ne fabrique pas le contexte de sécurité : cluster attendu, âge du blockhash, nonce account et nonce authority sont fournis explicitement lors de la conversion vers `ExecutionSimulationResult`. Depuis `pre.013`, `getAccountInfo` possède aussi un mode données complètes borné : le mode metadata-only conserve `dataSlice.length = 0`, tandis que `confirmed_with_data(max_data_bytes)` exige un tuple base64 complet dont la longueur décodée égale `space`.
|
||||
`kb_rpc` ne fabrique pas le contexte de sécurité : cluster attendu, âge du blockhash, nonce account et nonce authority sont fournis explicitement lors de la conversion vers `ExApiExecutionSimulationResult`. Depuis `pre.013`, `getAccountInfo` possède aussi un mode données complètes borné : le mode metadata-only conserve `dataSlice.length = 0`, tandis que `confirmed_with_data(max_data_bytes)` exige un tuple base64 complet dont la longueur décodée égale `space`.
|
||||
|
||||
## Assemblage et signature Solana
|
||||
|
||||
`0.4.2-pre.005` introduit `kb_execution_solana`, frontière commune entre les exécuteurs et les adaptateurs RPC. La crate convertit les `PlannedInstruction` en instructions SDK, compile le message avec son fee payer et sa source de blockhash, puis vérifie que les signataires réellement compilés correspondent exactement au contrat du plan.
|
||||
`0.4.2-pre.005` introduit `kb_execution_solana`, frontière commune entre les exécuteurs et les adaptateurs RPC. La crate convertit les `ExApiPlannedInstruction` en instructions SDK, compile le message avec son fee payer et sa source de blockhash, puis vérifie que les signataires réellement compilés correspondent exactement au contrat du plan.
|
||||
|
||||
La transaction non signée fournit deux sorties distinctes :
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ Certains protocoles Solana exigent de lire :
|
||||
- des séquences de logs liées à un CPI ;
|
||||
- des instructions voisines de la même transaction.
|
||||
|
||||
`CoreInstructionReplayInput` représente ce contrat de lecture : une instruction ciblée plus un contexte extrait depuis les tables `core`. Depuis le contrat `2`, ce contexte inclut également toutes les instructions outer de la signature, ordonnées numériquement et munies de leur payload retenu et de son hash.
|
||||
`MdCoreInstructionReplayInput` représente ce contrat de lecture : une instruction ciblée plus un contexte extrait depuis les tables `core`. Depuis le contrat `2`, ce contexte inclut également toutes les instructions outer de la signature, ordonnées numériquement et munies de leur payload retenu et de son hash.
|
||||
|
||||
## Sélection de replay
|
||||
|
||||
@@ -68,7 +68,7 @@ program_id = programme ciblé par le décodeur
|
||||
plage de slots = optionnelle
|
||||
```
|
||||
|
||||
Le repository charge les logs, balances, account keys et instructions outer nécessaires pour retourner `CoreInstructionReplayInput`. La liste outer inclut la cible et utilise les champs stables `instructionIndex`, `instructionPath`, `programId`, `payloadJson` et `payloadHash`. Cette extension lit les tables existantes et ne demande aucune migration.
|
||||
Le repository charge les logs, balances, account keys et instructions outer nécessaires pour retourner `MdCoreInstructionReplayInput`. La liste outer inclut la cible et utilise les champs stables `instructionIndex`, `instructionPath`, `programId`, `payloadJson` et `payloadHash`. Cette extension lit les tables existantes et ne demande aucune migration.
|
||||
|
||||
## Marquage de cycle de vie
|
||||
|
||||
|
||||
@@ -97,7 +97,7 @@ Ces identifiants sont détaillés dans `docs/CORE_PROGRAM_IDS.md`. Ils sont couv
|
||||
| `core_spl_single_pool_v1` | `SVSPxpvHdN29nkVg9rPapPNDddN5DipNLRUFhyjFThE` | `spl_single_pool` | `program` | `kb_decoder_spl_single_pool` | `core_specialized_reserved_current` |
|
||||
| `core_spl_name_service_v1` | `namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX` | `spl_name_service` | `program` | `kb_decoder_metadata_spl_name_service` | `core_specialized_reserved_current` |
|
||||
| `core_spl_stake_pool_v1` | `SPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHy` | `stake_pool` | `program` | `kb_decoder_spl_stake_pool` | `core_specialized_reserved_current` |
|
||||
| `core_spl_token_2022_v2022` | `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` | `token_2022` | `program` | `kb_decoder_spl_token_2022` | `core_handled` |
|
||||
| `core_spl_token_2022_v2022` | `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` | `token2022` | `program` | `kb_decoder_spl_token_2022` | `core_handled` |
|
||||
| `core_spl_token_2022_elgamal_registry_v1` | `regVYJW7tcT8zipN5YiBvHsvR5jXW1uLFxaHSbugABg` | `spl_token_2022_elgamal_registry` | `program` | `kb_decoder_spl_token_2022` | `core_specialized_reserved_current` |
|
||||
| `core_spl_token_v1` | `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` | `token` | `program` | `kb_decoder_spl_token` | `core_handled` |
|
||||
|
||||
|
||||
@@ -229,7 +229,7 @@ La mise en conformité est découpée avant toute nouvelle prérelease :
|
||||
1. `pre.035-delta-fix-002` : séparation des règles et audit automatisé reproductible ;
|
||||
2. correctifs suivants : points d'entrée de crates, réexports `pub`/`pub(crate)`, rustdocs et chemins `crate::...` ;
|
||||
3. correctifs suivants : imports de traits et suppression des imports ordinaires/groupés ;
|
||||
4. correctifs suivants : `TRACING_TARGET`, dépendances `tracing`, macros et matrice de routes ;
|
||||
4. correctifs suivants : `DC_METADATA_MTM_TRACING_TARGET`, dépendances `tracing`, macros et matrice de routes ;
|
||||
5. correctifs suivants : helpers dupliqués et mutualisation inter-crates ;
|
||||
6. fermeture : `cargo fmt --all`, audit strict, tests workspace et Clippy global.
|
||||
|
||||
|
||||
@@ -62,7 +62,7 @@ Le message à signer provient de `solana_transaction::Transaction::message_data(
|
||||
|
||||
## Identifiants natifs, Vote et loaders dans l’exécuteur
|
||||
|
||||
`solana-sdk-ids` est conservé intentionnellement comme registre officiel modulaire des adresses natives et sysvars. Les chemins `solana_sdk_ids::sysvar::{clock,rent,slot_hashes,instructions}` ne constituent pas un retour au SDK monolithique : ils fournissent uniquement des `Pubkey` canoniques. `solana-instructions-sysvar` ne doit être ajouté que lorsqu’une crate appelle réellement ses fonctions d’introspection d’instructions, pas pour remplacer un simple ID officiel.
|
||||
`solana-sdk-ids` est conservé intentionnellement comme registre officiel modulaire des adresses natives et sysvars. Les chemins `solana_sdk_ids::sysvar::{clock,rent,slot_hashes,instructions}` ne constituent pas un retour au SDK monolithique : ils fournissent uniquement des `MdPubkey` canoniques. `solana-instructions-sysvar` ne doit être ajouté que lorsqu’une crate appelle réellement ses fonctions d’introspection d’instructions, pas pour remplacer un simple ID officiel.
|
||||
|
||||
`kb_executor_solana_core` consomme `solana-vote-interface ^6.0` avec `serde` et `wincode` pour construire les vingt variantes wire Vote actuelles. Il utilise `solana-instruction` pour `Instruction`/`AccountMeta`, `solana-pubkey::Pubkey` pour les adresses publiques, `solana-hash::Hash` pour les hashes et `solana-sdk-ids` pour Rent, Clock et SlotHashes. Les quatre créations composées utilisent `solana-system-interface`; aucune dépendance `solana-sdk` ni feature `bincode` n’est ajoutée à la crate.
|
||||
|
||||
@@ -268,5 +268,5 @@ Le catalogue workspace déclare `mpl-token-metadata ^5.1` avec la seule feature
|
||||
|
||||
Le dépôt officiel `metaplex-foundation/mpl-token-metadata` confirme le Program ID `metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s`. L’IDL officiel audité porte la version `1.14.0` et le blob `5df4a24f62c2743125be096cc174680790c92c18`; l’inventaire Rust généré des instructions porte le blob `3c42eec629f82e44ba690a7c4bd2177cc78f1d49`.
|
||||
|
||||
`kb_decoder_metadata_metaplex_token_metadata` implémente désormais `InstructionDecoder` pour `CreateMetadataAccountV3` et `UpdateMetadataAccountV2`. Les arguments sont lus avec les types Borsh officiels et projetés avec la feature `serde`; les payloads, chaînes, créateurs, frais, comptes et suffixes sont bornés. L’enregistrement dans le registre runtime reste différé jusqu’à validation de ce premier groupe. Les metadata Token-2022 incorporées, Metaplex Core, Bubblegum et le JSON externe restent des provenances ou composants distincts.
|
||||
`kb_decoder_metadata_metaplex_token_metadata` implémente désormais `DcApiInstructionDecoder` pour `CreateMetadataAccountV3` et `UpdateMetadataAccountV2`. Les arguments sont lus avec les types Borsh officiels et projetés avec la feature `serde`; les payloads, chaînes, créateurs, frais, comptes et suffixes sont bornés. L’enregistrement dans le registre runtime reste différé jusqu’à validation de ce premier groupe. Les metadata Token-2022 incorporées, Metaplex Core, Bubblegum et le JSON externe restent des provenances ou composants distincts.
|
||||
|
||||
|
||||
@@ -18,8 +18,8 @@ Ce module fait partie du découpage strict de Khadhroony Bot2. Il doit conserver
|
||||
|
||||
## Contrats `0.4.0` et contexte core `2`
|
||||
|
||||
Le trait `InstructionDecoder` reçoit exclusivement `CoreInstructionReplayInput`. Il expose une identité et une version stables, les surfaces supportées, la couverture déclarée, la reconnaissance déterministe et un résultat explicite `decoded`, `ignored`, `unsupported` ou `failed`. Les observations produites conservent la preuve, la confiance, le statut on-chain et le caractère commité ou annulé.
|
||||
Le trait `DcApiInstructionDecoder` reçoit exclusivement `MdCoreInstructionReplayInput`. Il expose une identité et une version stables, les surfaces supportées, la couverture déclarée, la reconnaissance déterministe et un résultat explicite `decoded`, `ignored`, `unsupported` ou `failed`. Les observations produites conservent la preuve, la confiance, le statut on-chain et le caractère commité ou annulé.
|
||||
|
||||
Depuis `0.4.1-pre.014`, le même contrat inclut les payloads ordonnés des instructions outer. `contextual_input_hash` sérialise l’ensemble du contexte, trie récursivement les clés d’objets et conserve l’ordre des tableaux. Un changement de payload outer modifie donc le hash, tandis qu’un contexte identique produit un hash stable.
|
||||
Depuis `0.4.1-pre.014`, le même contrat inclut les payloads ordonnés des instructions outer. `decoder_api_decoder_api_contextual_input_hash` sérialise l’ensemble du contexte, trie récursivement les clés d’objets et conserve l’ordre des tableaux. Un changement de payload outer modifie donc le hash, tandis qu’un contexte identique produit un hash stable.
|
||||
|
||||
Le crate reste indépendant de PostgreSQL, Tauri et des fournisseurs RPC.
|
||||
|
||||
@@ -8,7 +8,7 @@ Décodeur contextualisé dédié au programme Metaplex Token Metadata.
|
||||
La crate suit la frontière commune des décodeurs opérationnels du workspace :
|
||||
|
||||
- `constants.rs` contient la surface, les discriminateurs, les bornes et la cible de tracing ;
|
||||
- `decoder.rs` implémente `ProtocolDecoder` et `InstructionDecoder` ;
|
||||
- `decoder.rs` implémente `DcApiProtocolDecoder` et `DcApiInstructionDecoder` ;
|
||||
- `instruction.rs` contient le décodage Borsh borné, la résolution des comptes et les observations ;
|
||||
- `lib.rs` réexporte le décodeur d’instructions et les types publics du parseur de comptes ;
|
||||
- le Program ID provient exclusivement de `kb_program_ids`.
|
||||
@@ -111,11 +111,11 @@ Le discriminant `50` décode `UpdateArgs` et toutes ses variantes publiées : `V
|
||||
|
||||
## `0.4.7-pre.025` — premier compte on-chain
|
||||
|
||||
La crate expose désormais `decode_metadata_account` pour le layout officiel `Metadata`. Le parseur refuse un owner étranger avant désérialisation, exige `Key::MetadataV1`, borne les données et les champs textuels, limite les creators, valide le PDA canonique `[metadata, program_id, mint]` et conserve le bump. Cette tranche ne couvre pas encore MasterEdition, Edition, EditionMarker, TokenRecord ni les records de délégation.
|
||||
La crate expose désormais `decoder_metadata_metaplex_token_metadata_decode_metadata_account` pour le layout officiel `Metadata`. Le parseur refuse un owner étranger avant désérialisation, exige `Key::MetadataV1`, borne les données et les champs textuels, limite les creators, valide le PDA canonique `[metadata, program_id, mint]` et conserve le bump. Cette tranche ne couvre pas encore MasterEdition, Edition, EditionMarker, TokenRecord ni les records de délégation.
|
||||
|
||||
## `0.4.7-pre.026` — comptes edition et master edition
|
||||
|
||||
La crate expose `decode_edition_account` pour `DeprecatedMasterEditionV1`, `MasterEditionV2` et `EditionV1`. Le décodeur vérifie l’owner avant parsing, exige le PDA commun `[metadata, program_id, mint, edition]`, conserve le bump et projette supply/max supply, printing mints historiques, parent et numéro d’édition. `MasterEditionV1` reste historique et decode-only ; `MasterEditionV2` et `EditionV1` alimenteront les futures projections stateful.
|
||||
La crate expose `decoder_metadata_metaplex_token_metadata_decode_edition_account` pour `DeprecatedMasterEditionV1`, `MasterEditionV2` et `EditionV1`. Le décodeur vérifie l’owner avant parsing, exige le PDA commun `[metadata, program_id, mint, edition]`, conserve le bump et projette supply/max supply, printing mints historiques, parent et numéro d’édition. `MasterEditionV1` reste historique et decode-only ; `MasterEditionV2` et `EditionV1` alimenteront les futures projections stateful.
|
||||
|
||||
## `0.4.7-pre.027` — Edition Marker V1/V2
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ Ce crate décode les programmes Solana natifs/runtime, les programmes historique
|
||||
|
||||
## Rôle dans l'écosystème
|
||||
|
||||
`SolanaCoreDecoder` implémente le contrat commun `InstructionDecoder` et consomme uniquement les inputs contextualisés produits par l’extraction core. Il ne dépend ni de PostgreSQL, ni de Tauri, ni d’un fournisseur RPC.
|
||||
`DcSolanaCoreDecoder` implémente le contrat commun `DcApiInstructionDecoder` et consomme uniquement les inputs contextualisés produits par l’extraction core. Il ne dépend ni de PostgreSQL, ni de Tauri, ni d’un fournisseur RPC.
|
||||
|
||||
Le processor conserve l’identité stable `solana_native_classifier` introduite en `0.4.0`. Cette continuité permet au ledger processor/version/hash de remplacer les anciens résultats `unsupported` lors d’un force replay. La version du processor reste `0.4.1` pendant les deltas préparatoires.
|
||||
|
||||
@@ -71,7 +71,7 @@ Chaque observation décodée contient notamment :
|
||||
|
||||
- `eventVersion` ;
|
||||
- program ID, surface et entry code ;
|
||||
- signature, slot et chemin outer/inner via `DecodedProtocolEvent` ;
|
||||
- signature, slot et chemin outer/inner via `MdDecodedProtocolEvent` ;
|
||||
- paramètres numériques sans perte ;
|
||||
- comptes résolus avec rôle, index, clé et privilèges attendus/observés ;
|
||||
- `transactionSucceeded` ;
|
||||
|
||||
@@ -11,7 +11,7 @@ Ce crate décode les programmes SPL Memo v1, v3 et v4 depuis l’instruction cor
|
||||
- v3 : `MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr` ;
|
||||
- v4 : `Memo4c2pN8afCj432Lb7RMVKi9PbQnnW7ewFFaV3oAH`.
|
||||
|
||||
`SplMemoDecoder` implémente le contrat contextualisé `InstructionDecoder`. La reconnaissance est exacte pour ces trois IDs et incompatible avec tout autre programme. L’adaptateur historique `ProtocolDecoder` déclare `Yes` pour ces IDs, mais ne fabrique pas d’événement sans instruction contextualisée.
|
||||
`DcSplMemoDecoder` implémente le contrat contextualisé `DcApiInstructionDecoder`. La reconnaissance est exacte pour ces trois IDs et incompatible avec tout autre programme. L’adaptateur historique `DcApiProtocolDecoder` déclare `Yes` pour ces IDs, mais ne fabrique pas d’événement sans instruction contextualisée.
|
||||
|
||||
## Contrat décodé
|
||||
|
||||
|
||||
@@ -24,10 +24,10 @@ est `docs/SPL_TOKEN_MATRIX.json`.
|
||||
|
||||
## Contrat de décodage
|
||||
|
||||
`SplTokenDecoder` implémente les deux contrats communs :
|
||||
`DcSplTokenDecoder` implémente les deux contrats communs :
|
||||
|
||||
- `ProtocolDecoder` annonce `Yes` uniquement pour le Program ID Token classique exact ;
|
||||
- `InstructionDecoder` fournit une surface, 28 déclarations de couverture, une reconnaissance par
|
||||
- `DcApiProtocolDecoder` annonce `Yes` uniquement pour le Program ID Token classique exact ;
|
||||
- `DcApiInstructionDecoder` fournit une surface, 28 déclarations de couverture, une reconnaissance par
|
||||
tag et un résultat contextualisé pour le replay commun.
|
||||
|
||||
Chaque observation conserve le tag, le wire borné et son SHA-256, le chemin outer/inner, les
|
||||
@@ -58,7 +58,7 @@ comptes insuffisants ou batch imbriqué échoue avec un diagnostic borné.
|
||||
|
||||
## Limites actuelles
|
||||
|
||||
- Le contrat `CoreInstructionReplayInput` ne transporte pas encore les return data canoniques ; les
|
||||
- Le contrat `MdCoreInstructionReplayInput` ne transporte pas encore les return data canoniques ; les
|
||||
trois conversions concernées restent décodées comme intentions, avec validation de return data
|
||||
explicitement indisponible.
|
||||
- Le corpus Mainnet prouve les opérations réellement observées, pas l'exhaustivité des 28 tags sur
|
||||
|
||||
@@ -11,56 +11,56 @@ Cette crate définit les contrats communs de la couche d’exécution. Elle ne d
|
||||
|
||||
| Export | Usage |
|
||||
|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
|
||||
| `ExecutionCapability` | Réponse exacte `Supported { operation_code }` ou `Unsupported { reason_code, reason }` pour un couple programme/opération. |
|
||||
| `ExApiExecutionCapability` | Réponse exacte `Supported { operation_code }` ou `Unsupported { reason_code, reason }` pour un couple programme/opération. |
|
||||
| `ExecutionCapability::supported(...)` | Construit une capacité supportée avec un code stable. |
|
||||
| `ExecutionCapability::unsupported(...)` | Construit un refus documenté avec code et message. |
|
||||
| `ExecutionCapability::is_supported()` | Teste la capacité sans perdre le diagnostic du variant complet. |
|
||||
| `TypedInstructionExecutor` | Contrat actuel : expose `capability(...)` et `build_prepared_plan(...)` sans I/O, signature ou envoi. |
|
||||
| `InstructionExecutor` | Pont historique fondé sur `ExecutionRequest`/`ExecutionPlan`; il reste disponible pour les crates réservées. |
|
||||
| `ExecutionSupport` | Résultat historique `No`, `Maybe` ou `Yes`; les exécuteurs opérationnels doivent éviter `Maybe`. |
|
||||
| `ExApiTypedInstructionExecutor` | Contrat actuel : expose `capability(...)` et `build_prepared_plan(...)` sans I/O, signature ou envoi. |
|
||||
| `ExApiInstructionExecutor` | Pont historique fondé sur `ExApiExecutionRequest`/`ExApiExecutionPlan`; il reste disponible pour les crates réservées. |
|
||||
| `ExApiExecutionSupport` | Résultat historique `No`, `Maybe` ou `Yes`; les exécuteurs opérationnels doivent éviter `Maybe`. |
|
||||
|
||||
### Politiques
|
||||
|
||||
| Export | Usage |
|
||||
|---------------------------------|-----------------------------------------------------------------------------------------------------------|
|
||||
| `ExecutionPolicy` | Agrège cluster, simulation, blockhash/nonce, plafonds, signataires autorisés, dry-run et post-validation. |
|
||||
| `ExecutionCluster` | Cluster attendu : Localnet, Devnet, Testnet ou Mainnet. |
|
||||
| `ExecutionClusterPolicy` | Autorisation du cluster et double confirmation Mainnet. |
|
||||
| `ExecutionSimulationPolicy` | Indique si la simulation est obligatoire. |
|
||||
| `ExecutionBlockhashKind` | Sélectionne un recent blockhash ou un durable nonce. |
|
||||
| `ExecutionBlockhashPolicy` | Porte l’âge maximal du blockhash ou le compte et l’autorité nonce. |
|
||||
| `ExecutionCostLimit` | Plafonds de dépense, frais totaux et prix par compute unit. |
|
||||
| `PostExecutionValidationPolicy` | Étapes exigées après confirmation : canonical insert, core extraction, decode replay et matérialisation. |
|
||||
| Export | Usage |
|
||||
|--------------------------------------|-----------------------------------------------------------------------------------------------------------|
|
||||
| `ExApiExecutionPolicy` | Agrège cluster, simulation, blockhash/nonce, plafonds, signataires autorisés, dry-run et post-validation. |
|
||||
| `ExApiExecutionCluster` | Cluster attendu : Localnet, Devnet, Testnet ou Mainnet. |
|
||||
| `ExApiExecutionClusterPolicy` | Autorisation du cluster et double confirmation Mainnet. |
|
||||
| `ExApiExecutionSimulationPolicy` | Indique si la simulation est obligatoire. |
|
||||
| `ExApiExecutionBlockhashKind` | Sélectionne un recent blockhash ou un durable nonce. |
|
||||
| `ExApiExecutionBlockhashPolicy` | Porte l’âge maximal du blockhash ou le compte et l’autorité nonce. |
|
||||
| `ExApiExecutionCostLimit` | Plafonds de dépense, frais totaux et prix par compute unit. |
|
||||
| `ExApiPostExecutionValidationPolicy` | Étapes exigées après confirmation : canonical insert, core extraction, decode replay et matérialisation. |
|
||||
|
||||
Tous les types de politique implémentent des valeurs par défaut conservatrices : Devnet, simulation obligatoire, recent blockhash borné, dry-run actif et Mainnet désactivé.
|
||||
|
||||
### Plan préparé
|
||||
|
||||
| Export | Usage |
|
||||
|-------------------------|-------------------------------------------------------------------------------------|
|
||||
| `PreparedExecutionPlan` | Contrat immutable transmis de l’exécuteur à la sécurité puis à l’assembleur Solana. |
|
||||
| `PlannedInstruction` | Program ID, code d’opération, comptes ordonnés et payload exact. |
|
||||
| `PlannedAccount` | Public key et flags signer/writable d’un compte d’instruction. |
|
||||
| `RequiredSigner` | Public key et rôle stable d’un signataire requis. |
|
||||
| Export | Usage |
|
||||
|------------------------------|-------------------------------------------------------------------------------------|
|
||||
| `ExApiPreparedExecutionPlan` | Contrat immutable transmis de l’exécuteur à la sécurité puis à l’assembleur Solana. |
|
||||
| `ExApiPlannedInstruction` | Program ID, code d’opération, comptes ordonnés et payload exact. |
|
||||
| `ExApiPlannedAccount` | Public key et flags signer/writable d’un compte d’instruction. |
|
||||
| `ExApiRequiredSigner` | Public key et rôle stable d’un signataire requis. |
|
||||
|
||||
Un plan contient également l’exécuteur/version, l’identifiant d’intent, le fee payer, la politique, les lamports dépensés ou verrouillés et le prix Compute Budget demandé.
|
||||
|
||||
### Résultats d’orchestration
|
||||
|
||||
| Export | Usage |
|
||||
|-------------------------------|-------------------------------------------------------------------------------------------------------------------|
|
||||
| `ExecutionSimulationResult` | Preuve provider-neutral d’une simulation, avec contexte cluster/blockhash, frais, unités, logs et erreur runtime. |
|
||||
| `ExecutionSendResult` | Signature acceptée par le RPC et slot de soumission éventuel. |
|
||||
| `ExecutionConfirmationStatus` | État final ou intermédiaire de confirmation. |
|
||||
| `ExecutionConfirmationResult` | Résultat borné des polls de confirmation. |
|
||||
| `PostExecutionDiagnostic` | Résumé des étapes canonical/core/decode/materialization après exécution. |
|
||||
| Export | Usage |
|
||||
|------------------------------------|-------------------------------------------------------------------------------------------------------------------|
|
||||
| `ExApiExecutionSimulationResult` | Preuve provider-neutral d’une simulation, avec contexte cluster/blockhash, frais, unités, logs et erreur runtime. |
|
||||
| `ExApiExecutionSendResult` | Signature acceptée par le RPC et slot de soumission éventuel. |
|
||||
| `ExApiExecutionConfirmationStatus` | État final ou intermédiaire de confirmation. |
|
||||
| `ExApiExecutionConfirmationResult` | Résultat borné des polls de confirmation. |
|
||||
| `ExApiPostExecutionDiagnostic` | Résumé des étapes canonical/core/decode/materialization après exécution. |
|
||||
|
||||
### Compatibilité et helpers JSON
|
||||
|
||||
| Export | Usage |
|
||||
|--------------------------------------|------------------------------------------------------------------------|
|
||||
| `ExecutionRequest` | Requête historique `program_id + operation_code + payload_json`. |
|
||||
| `ExecutionPlan` | Plan historique sérialisé, sans garantie d’être directement envoyable. |
|
||||
| `ExApiExecutionRequest` | Requête historique `program_id + operation_code + payload_json`. |
|
||||
| `ExApiExecutionPlan` | Plan historique sérialisé, sans garantie d’être directement envoyable. |
|
||||
| `serialize_payload_json(...)` | Sérialise un `serde_json::Value` compact avec `kb_core::Error`. |
|
||||
| `serialize_payload_json_pretty(...)` | Sérialise le même payload en forme lisible. |
|
||||
|
||||
|
||||
@@ -16,11 +16,11 @@ Cette crate applique des contrôles stateless communs aux plans préparés avant
|
||||
|
||||
### `ExecutionSafetyChecker::evaluate_plan(plan)`
|
||||
|
||||
Évalue l’ancien `ExecutionPlan`. Ce contrat historique ne contient pas assez d’informations pour autoriser directement une exécution ; la décision reste donc conservatrice et exige une confirmation.
|
||||
Évalue l’ancien `ExApiExecutionPlan`. Ce contrat historique ne contient pas assez d’informations pour autoriser directement une exécution ; la décision reste donc conservatrice et exige une confirmation.
|
||||
|
||||
### `ExecutionSafetyChecker::evaluate_prepared_plan(plan)`
|
||||
|
||||
Décide si un `PreparedExecutionPlan` peut atteindre la simulation RPC. La fonction vérifie notamment :
|
||||
Décide si un `ExApiPreparedExecutionPlan` peut atteindre la simulation RPC. La fonction vérifie notamment :
|
||||
|
||||
- présence d’instructions et de signataires ;
|
||||
- simulation obligatoire ;
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
# kb_execution_solana
|
||||
|
||||
`kb_execution_solana` transforme un `PreparedExecutionPlan` commun en message et transaction Solana, puis résout les signataires via l’interface Solana `Signer` et signe uniquement après une simulation autorisée par `kb_execution_safety`.
|
||||
`kb_execution_solana` transforme un `ExApiPreparedExecutionPlan` commun en message et transaction Solana, puis résout les signataires via l’interface Solana `Signer` et signe uniquement après une simulation autorisée par `kb_execution_safety`.
|
||||
|
||||
La crate est indépendante des exécuteurs concrets et des transports RPC. Elle assemble aussi bien les plans à recent blockhash que les transactions consommant réellement un durable nonce.
|
||||
|
||||
|
||||
@@ -18,10 +18,10 @@ Elle ne charge aucun wallet, ne signe rien, n’appelle aucun RPC et n’envoie
|
||||
|
||||
| Fonction | Paramètres | Résultat | Rôle |
|
||||
|-------------------------------------------------|--------------------------------------------------|------------------------------------------|------------------------------------------------------------------------------------------------------------------|
|
||||
| `TypedInstructionExecutor::capability` | `program_id: &ProgramId`, `operation_code: &str` | `ExecutionCapability` | Indique exactement si le couple programme/opération possède un builder. |
|
||||
| `TypedInstructionExecutor::capability` | `program_id: &ProgramId`, `operation_code: &str` | `ExApiExecutionCapability` | Indique exactement si le couple programme/opération possède un builder. |
|
||||
| `TypedInstructionExecutor::build_prepared_plan` | `intent: &SolanaCoreExecutionIntent` | `kb_core::Result<PreparedExecutionPlan>` | Valide l’intent, construit l’instruction officielle et déclare comptes, signataires, coût et politique. |
|
||||
| `InstructionExecutor::program_ids` | aucun | `&'static [&'static str]` | Retourne les dix-huit program IDs natifs classifiés par la crate. |
|
||||
| `InstructionExecutor::supports_request` | `request: &ExecutionRequest` | `ExecutionSupport` | Pont historique exact `Yes/No`, sans état `Maybe`. |
|
||||
| `InstructionExecutor::supports_request` | `request: &ExecutionRequest` | `ExApiExecutionSupport` | Pont historique exact `Yes/No`, sans état `Maybe`. |
|
||||
| `InstructionExecutor::build_plan` | `request: &ExecutionRequest` | `kb_core::Result<ExecutionPlan>` | Désérialise un `SolanaCoreExecutionIntent`, construit le plan typé puis le sérialise dans le contrat historique. |
|
||||
|
||||
### Types et constantes réexportés
|
||||
@@ -52,7 +52,7 @@ Elle ne charge aucun wallet, ne signe rien, n’appelle aucun RPC et n’envoie
|
||||
| `LOADER_V3_*_OPERATION` | Codes stables des onze plans Loader v3. |
|
||||
| `LOADER_V4_*_OPERATION` | Codes stables des neuf plans Loader v4. |
|
||||
|
||||
Les modules internes ne sont pas publics. Les appelants utilisent les réexports de `lib.rs` et les traits de `kb_execution_api`. Le module privé `validation` centralise le parsing des `Pubkey`, les IDs natifs, les contrôles de longueur, de montants positifs, de comptes distincts, de dérivation seedée et la construction d’erreurs partagées ; les modules de programme conservent uniquement leurs règles et libellés métier.
|
||||
Les modules internes ne sont pas publics. Les appelants utilisent les réexports de `lib.rs` et les traits de `kb_execution_api`. Le module privé `validation` centralise le parsing des `MdPubkey`, les IDs natifs, les contrôles de longueur, de montants positifs, de comptes distincts, de dérivation seedée et la construction d’erreurs partagées ; les modules de programme conservent uniquement leurs règles et libellés métier.
|
||||
|
||||
## Contrat d’intent et résultat
|
||||
|
||||
@@ -69,10 +69,10 @@ SolanaCoreExecutionIntent {
|
||||
|
||||
- `intent_id` : identifiant stable fourni par l’appelant pour les logs et la corrélation ;
|
||||
- `fee_payer` : compte qui paiera les frais de transaction ;
|
||||
- `policy` : `ExecutionPolicy` évaluée séparément par `kb_execution_safety` ;
|
||||
- `policy` : `ExApiExecutionPolicy` évaluée séparément par `kb_execution_safety` ;
|
||||
- `operation` : variante typée de `SolanaCoreOperation`.
|
||||
|
||||
Le résultat `PreparedExecutionPlan` contient :
|
||||
Le résultat `ExApiPreparedExecutionPlan` contient :
|
||||
|
||||
- l’exécuteur et sa version ;
|
||||
- le code d’opération ;
|
||||
@@ -114,11 +114,11 @@ Cent neuf opérations disposent d’un builder : dix-sept System, quatre Compute
|
||||
SolanaCoreOperation::SystemTransfer { from, to, lamports }
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|------------|----------|-----------------------------------------|
|
||||
| `from` | `Pubkey` | Compte source writable et signataire. |
|
||||
| `to` | `Pubkey` | Compte destinataire writable. |
|
||||
| `lamports` | `u64` | Montant transféré, strictement positif. |
|
||||
| Paramètre | Type | Description |
|
||||
|------------|------------|-----------------------------------------|
|
||||
| `from` | `MdPubkey` | Compte source writable et signataire. |
|
||||
| `to` | `MdPubkey` | Compte destinataire writable. |
|
||||
| `lamports` | `u64` | Montant transféré, strictement positif. |
|
||||
|
||||
**Résultat et effet :** une instruction System `Transfer`. Le plan exige `from`, ajoute le fee payer si nécessaire et reporte `lamports` dans `requested_spend_lamports`.
|
||||
|
||||
@@ -146,14 +146,14 @@ SolanaCoreOperation::SystemTransferWithSeed {
|
||||
}
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|--------------|----------|------------------------------------------------------------|
|
||||
| `from` | `Pubkey` | Compte source dérivé, writable mais non signataire direct. |
|
||||
| `from_base` | `Pubkey` | Base de dérivation et signataire requis. |
|
||||
| `from_seed` | `String` | Seed utilisé pour dériver `from`. |
|
||||
| `from_owner` | `Pubkey` | Owner utilisé dans la dérivation de `from`. |
|
||||
| `to` | `Pubkey` | Destinataire writable. |
|
||||
| `lamports` | `u64` | Montant strictement positif. |
|
||||
| Paramètre | Type | Description |
|
||||
|--------------|------------|------------------------------------------------------------|
|
||||
| `from` | `MdPubkey` | Compte source dérivé, writable mais non signataire direct. |
|
||||
| `from_base` | `MdPubkey` | Base de dérivation et signataire requis. |
|
||||
| `from_seed` | `String` | Seed utilisé pour dériver `from`. |
|
||||
| `from_owner` | `MdPubkey` | Owner utilisé dans la dérivation de `from`. |
|
||||
| `to` | `MdPubkey` | Destinataire writable. |
|
||||
| `lamports` | `u64` | Montant strictement positif. |
|
||||
|
||||
**Résultat et effet :** une instruction System `TransferWithSeed`. Le builder recalcule `Pubkey::create_with_seed(from_base, from_seed, from_owner)` et refuse l’intent si l’adresse obtenue diffère de `from`.
|
||||
|
||||
@@ -169,13 +169,13 @@ SolanaCoreOperation::SystemCreateAccount {
|
||||
}
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|---------------|----------|---------------------------------------------------------------------------------|
|
||||
| `from` | `Pubkey` | Compte de financement writable et signataire. |
|
||||
| `new_account` | `Pubkey` | Nouveau compte writable et signataire. |
|
||||
| `lamports` | `u64` | Financement initial, strictement positif. |
|
||||
| `space` | `u64` | Taille de données allouée ; zéro est valide pour un compte System sans données. |
|
||||
| `owner` | `Pubkey` | Programme propriétaire après création. |
|
||||
| Paramètre | Type | Description |
|
||||
|---------------|------------|---------------------------------------------------------------------------------|
|
||||
| `from` | `MdPubkey` | Compte de financement writable et signataire. |
|
||||
| `new_account` | `MdPubkey` | Nouveau compte writable et signataire. |
|
||||
| `lamports` | `u64` | Financement initial, strictement positif. |
|
||||
| `space` | `u64` | Taille de données allouée ; zéro est valide pour un compte System sans données. |
|
||||
| `owner` | `MdPubkey` | Programme propriétaire après création. |
|
||||
|
||||
**Résultat et effet :** une instruction officielle `CreateAccount` qui finance, alloue et assigne le compte. Le calcul du minimum rent-exempt appartient à la couche RPC/orchestration.
|
||||
|
||||
@@ -193,15 +193,15 @@ SolanaCoreOperation::SystemCreateAccountWithSeed {
|
||||
}
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|---------------|----------|------------------------------------------------------|
|
||||
| `from` | `Pubkey` | Compte de financement writable et signataire. |
|
||||
| `new_account` | `Pubkey` | Adresse créée à partir de `base`, `seed` et `owner`. |
|
||||
| `base` | `Pubkey` | Base signataire ; elle peut être identique à `from`. |
|
||||
| `seed` | `String` | Seed borné par l’interface Solana. |
|
||||
| `lamports` | `u64` | Financement initial strictement positif. |
|
||||
| `space` | `u64` | Taille allouée, zéro compris. |
|
||||
| `owner` | `Pubkey` | Owner du compte et composant de sa dérivation. |
|
||||
| Paramètre | Type | Description |
|
||||
|---------------|------------|------------------------------------------------------|
|
||||
| `from` | `MdPubkey` | Compte de financement writable et signataire. |
|
||||
| `new_account` | `MdPubkey` | Adresse créée à partir de `base`, `seed` et `owner`. |
|
||||
| `base` | `MdPubkey` | Base signataire ; elle peut être identique à `from`. |
|
||||
| `seed` | `String` | Seed borné par l’interface Solana. |
|
||||
| `lamports` | `u64` | Financement initial strictement positif. |
|
||||
| `space` | `u64` | Taille allouée, zéro compris. |
|
||||
| `owner` | `MdPubkey` | Owner du compte et composant de sa dérivation. |
|
||||
|
||||
**Résultat et effet :** une instruction `CreateAccountWithSeed`. Le builder recalcule l’adresse dérivée avant de construire le plan et déduplique `from`/`base` lorsqu’ils désignent le même signataire.
|
||||
|
||||
@@ -219,11 +219,11 @@ SolanaCoreOperation::SystemCreateAccountAllowPrefund {
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|---------------|------------------|------------------------------------------------------------------|
|
||||
| `new_account` | `Pubkey` | Compte préfinancé à créer, writable et toujours signataire. |
|
||||
| `new_account` | `MdPubkey` | Compte préfinancé à créer, writable et toujours signataire. |
|
||||
| `payer` | `Option<Pubkey>` | Payer writable/signataire pour des lamports additionnels. |
|
||||
| `lamports` | `u64` | Montant additionnel ; doit être zéro lorsque `payer` est absent. |
|
||||
| `space` | `u64` | Taille de données à allouer, zéro compris. |
|
||||
| `owner` | `Pubkey` | Programme propriétaire après création. |
|
||||
| `owner` | `MdPubkey` | Programme propriétaire après création. |
|
||||
|
||||
**Résultat et effet :** une instruction `CreateAccountAllowPrefund`, qui n’impose pas un solde initial nul. Cette opération peut verrouiller tout le solde existant dans le compte assigné ; elle doit être protégée par une politique appelante stricte et peut dépendre de l’activation runtime correspondante sur le cluster ciblé.
|
||||
|
||||
@@ -233,10 +233,10 @@ SolanaCoreOperation::SystemCreateAccountAllowPrefund {
|
||||
SolanaCoreOperation::SystemAllocate { account, space }
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|----------|---------------------------------------|
|
||||
| `account` | `Pubkey` | Compte System writable et signataire. |
|
||||
| `space` | `u64` | Nouvelle taille strictement positive. |
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|------------|---------------------------------------|
|
||||
| `account` | `MdPubkey` | Compte System writable et signataire. |
|
||||
| `space` | `u64` | Nouvelle taille strictement positive. |
|
||||
|
||||
**Résultat et effet :** une instruction `Allocate`. Elle ne finance pas le compte et ne change pas son propriétaire.
|
||||
|
||||
@@ -252,13 +252,13 @@ SolanaCoreOperation::SystemAllocateWithSeed {
|
||||
}
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|----------|--------------------------------------------------------|
|
||||
| `account` | `Pubkey` | Compte dérivé writable. |
|
||||
| `base` | `Pubkey` | Base de dérivation et signataire requis. |
|
||||
| `seed` | `String` | Seed de dérivation. |
|
||||
| `space` | `u64` | Taille strictement positive. |
|
||||
| `owner` | `Pubkey` | Owner utilisé dans la dérivation et assigné au compte. |
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|------------|--------------------------------------------------------|
|
||||
| `account` | `MdPubkey` | Compte dérivé writable. |
|
||||
| `base` | `MdPubkey` | Base de dérivation et signataire requis. |
|
||||
| `seed` | `String` | Seed de dérivation. |
|
||||
| `space` | `u64` | Taille strictement positive. |
|
||||
| `owner` | `MdPubkey` | Owner utilisé dans la dérivation et assigné au compte. |
|
||||
|
||||
**Résultat et effet :** une instruction `AllocateWithSeed`. L’adresse `account` est recalculée et validée avant construction.
|
||||
|
||||
@@ -268,10 +268,10 @@ SolanaCoreOperation::SystemAllocateWithSeed {
|
||||
SolanaCoreOperation::SystemAssign { account, owner }
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|----------|---------------------------------------|
|
||||
| `account` | `Pubkey` | Compte System writable et signataire. |
|
||||
| `owner` | `Pubkey` | Nouveau programme propriétaire. |
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|------------|---------------------------------------|
|
||||
| `account` | `MdPubkey` | Compte System writable et signataire. |
|
||||
| `owner` | `MdPubkey` | Nouveau programme propriétaire. |
|
||||
|
||||
**Résultat et effet :** une instruction `Assign`. Elle ne transfère aucun lamport et n’alloue aucune donnée.
|
||||
|
||||
@@ -286,12 +286,12 @@ SolanaCoreOperation::SystemAssignWithSeed {
|
||||
}
|
||||
```
|
||||
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|----------|------------------------------------------------------|
|
||||
| `account` | `Pubkey` | Compte dérivé writable. |
|
||||
| `base` | `Pubkey` | Base de dérivation et signataire requis. |
|
||||
| `seed` | `String` | Seed de dérivation. |
|
||||
| `owner` | `Pubkey` | Nouvel owner et composant de la dérivation attendue. |
|
||||
| Paramètre | Type | Description |
|
||||
|-----------|------------|------------------------------------------------------|
|
||||
| `account` | `MdPubkey` | Compte dérivé writable. |
|
||||
| `base` | `MdPubkey` | Base de dérivation et signataire requis. |
|
||||
| `seed` | `String` | Seed de dérivation. |
|
||||
| `owner` | `MdPubkey` | Nouvel owner et composant de la dérivation attendue. |
|
||||
|
||||
**Résultat et effet :** une instruction `AssignWithSeed`. Le builder refuse une adresse qui ne correspond pas exactement à `base + seed + owner`.
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ La construction de plan est `Supported` pour `AddMemo` uniquement sur l'ID v4 ex
|
||||
|
||||
La disponibilité effective de v4 sur un cluster n’est pas supposée par le builder : elle est établie par la simulation RPC obligatoire. Une future génération expérimentale officiellement encodée pourra être ajoutée sans la limiter artificiellement à un cluster. Les générations historiques restent décodables dans `kb_decoder_spl_memo`, mais ne sont pas exécutables. La démo `0.4.3` reste limitée à Devnet.
|
||||
|
||||
Les signataires restent visibles dans `PreparedExecutionPlan` avant toute signature. Les clés privées ne font partie ni de l’intent ni du plan.
|
||||
Les signataires restent visibles dans `ExApiPreparedExecutionPlan` avant toute signature. Les clés privées ne font partie ni de l’intent ni du plan.
|
||||
|
||||
## Validation Devnet et démos
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ obsolètes. Les variantes checked doivent être préférées lorsqu’un mint et
|
||||
`SplTokenExecutionIntent` contient :
|
||||
|
||||
- un identifiant d’intent et un fee payer ;
|
||||
- une `ExecutionPolicy` commune, simulation obligatoire et dry-run par défaut ;
|
||||
- une `ExApiExecutionPolicy` commune, simulation obligatoire et dry-run par défaut ;
|
||||
- une instruction typée ou un `Batch` de sous-instructions non batch ;
|
||||
- les comptes métier explicites ;
|
||||
- une autorité simple ou un multisig avec signataires ordonnés ;
|
||||
@@ -71,7 +71,7 @@ instruction Token ; le préflight stateful de la tranche suivante les vérifiera
|
||||
Les montants token ne sont pas des frais réseau et ne sont pas reportés comme lamports dépensés.
|
||||
Un montant explicite `UnwrapLamports` est déclaré dans `requested_spend_lamports`; un unwrap total
|
||||
et `WithdrawExcessLamports` restent simulation-only tant qu’une lecture d’état n’a pas borné les
|
||||
lamports déplaçables. Le plafond de frais reste séparé dans `ExecutionCostLimit`.
|
||||
lamports déplaçables. Le plafond de frais reste séparé dans `ExApiExecutionCostLimit`.
|
||||
|
||||
Toute construction impose une simulation, un plafond de frais positif, une insertion canonique,
|
||||
l’extraction core et le replay décodé. Les mutations exigent aussi la validation de matérialisation ;
|
||||
|
||||
@@ -22,4 +22,4 @@ Les instructions ATA ne modifient aucune autorité de mint, freeze, close ou mul
|
||||
|
||||
## État ElGamal Registry
|
||||
|
||||
`materialize_elgamal_registry_state_snapshot` projette l’état exact lu du compte registre (`owner`, clé ElGamal publique et wire). Cette projection ne prétend pas revalider la preuve cryptographique depuis les seuls octets du compte et ne déchiffre aucune valeur.
|
||||
`materializer_admin_materialize_elgamal_registry_state_snapshot` projette l’état exact lu du compte registre (`owner`, clé ElGamal publique et wire). Cette projection ne prétend pas revalider la preuve cryptographique depuis les seuls octets du compte et ne déchiffre aucune valeur.
|
||||
|
||||
@@ -18,7 +18,7 @@ Ce module fait partie du découpage strict de Khadhroony Bot2. Il doit conserver
|
||||
|
||||
## Contrats `0.4.0`
|
||||
|
||||
Le trait `EventMaterializer` consomme des observations décodées stables et déclare les familles acceptées, l’applicabilité exacte par observation ainsi que la politique applicable aux transactions réussies ou échouées. Les sorties possèdent des clés idempotentes et un statut explicite `inserted`, `replaced`, `ignored`, `refused` ou `failed`.
|
||||
Le trait `MtApiEventMaterializer` consomme des observations décodées stables et déclare les familles acceptées, l’applicabilité exacte par observation ainsi que la politique applicable aux transactions réussies ou échouées. Les sorties possèdent des clés idempotentes et un statut explicite `inserted`, `replaced`, `ignored`, `refused` ou `failed`.
|
||||
|
||||
La garde commune refuse toute matérialisation de trade, liquidité ou lifecycle supposée réussie depuis une observation échouée ou non commitée.
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ Une même réalité métier possède une seule projection canonique. Lorsqu’un
|
||||
|
||||
## Metaplex Token Metadata
|
||||
|
||||
`materialize_metaplex_metadata_snapshot` matérialise un `CanonicalMetadataAccountSnapshot` de type `MetadataV1` lorsque sa provenance est commitée.
|
||||
`materialize_metaplex_metadata_snapshot` matérialise un `DcMetadataMtmCanonicalMetadataAccountSnapshot` de type `MetadataV1` lorsque sa provenance est commitée.
|
||||
|
||||
La projection conserve notamment :
|
||||
|
||||
@@ -32,7 +32,7 @@ Une provenance non commitée ou un autre layout est refusé.
|
||||
|
||||
## Token-2022 incorporé
|
||||
|
||||
`materialize_token_2022_metadata_snapshot` projette uniquement les extensions `TokenMetadata`, `TokenGroup` et `TokenGroupMember` d’un état Mint déjà parsé et borné. La provenance reste `token_2022_embedded_tlv`; aucun URI externe n’est téléchargé et aucune donnée Metaplex n’est fusionnée implicitement.
|
||||
`materialize_token2022_metadata_snapshot` projette uniquement les extensions `TokenMetadata`, `TokenGroup` et `TokenGroupMember` d’un état Mint déjà parsé et borné. La provenance reste `token_2022_embedded_tlv`; aucun URI externe n’est téléchargé et aucune donnée Metaplex n’est fusionnée implicitement.
|
||||
|
||||
Les conflits éventuels entre Metaplex, Token-2022 embedded metadata et futures sources externes doivent être résolus par une politique de provenance explicite, jamais par écrasement silencieux.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ Ce module fait partie du découpage strict de Khadhroony Bot2. Il doit conserver
|
||||
|
||||
## Contrat canonique `0.3.2`
|
||||
|
||||
Le crate expose maintenant `CanonicalTransaction` et les structures associées pour représenter une transaction Solana indépendamment de sa source. Le contrat couvre les transactions legacy et v0, les comptes statiques et chargés par ALT, les instructions externes et internes, les logs, les balances SOL/SPL, les erreurs, rewards, return data, compute units et block time.
|
||||
Le crate expose maintenant `MdCanonicalTransaction` et les structures associées pour représenter une transaction Solana indépendamment de sa source. Le contrat couvre les transactions legacy et v0, les comptes statiques et chargés par ALT, les instructions externes et internes, les logs, les balances SOL/SPL, les erreurs, rewards, return data, compute units et block time.
|
||||
|
||||
La sérialisation canonique :
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ Le crate expose `execute_http_backfill`, `BackfillRequest`, `BackfillSource` et
|
||||
## Replay decode `0.4.0`
|
||||
|
||||
`execute_decode_replay` sélectionne des instructions core contextualisées par signatures, états, slots, program IDs et instruction paths. Il applique un dispatch déterministe, une concurrence bornée, l’arrêt coopératif, le skip processor/version/hash, un force replay obligatoirement borné par signatures ou par autorisation « toutes les signatures », et la persistance atomique via `DecodePipelineStore`.
|
||||
Depuis `0.4.1-pre.014`, le contrat core `2` ajoute les instructions outer ordonnées au calcul de `contextual_input_hash`. `DECODE_PIPELINE_VERSION` reste `1` : le changement de contrat est déjà versionné et force naturellement un nouveau hash. Après application du delta, un force replay est nécessaire pour remplacer les résultats calculés avec le contrat `1`. Les transactions, rollbacks et clés d’idempotence du pipeline restent inchangés.
|
||||
Depuis `0.4.1-pre.014`, le contrat core `2` ajoute les instructions outer ordonnées au calcul de `decoder_api_decoder_api_contextual_input_hash`. `DECODE_PIPELINE_VERSION` reste `1` : le changement de contrat est déjà versionné et force naturellement un nouveau hash. Après application du delta, un force replay est nécessaire pour remplacer les résultats calculés avec le contrat `1`. Les transactions, rollbacks et clés d’idempotence du pipeline restent inchangés.
|
||||
|
||||
La matérialisation reste optionnelle, exige au moins un matérialiseur enregistré et n’est appelée qu’après la persistance réussie du décodage. Depuis `0.4.1-pre.005`, la sélection vérifie d’abord l’applicabilité exacte surface/entrée ; les observations de même famille mais hors périmètre ne créent plus de faux refus. Le résumé distingue les statuts par processor, les skips, les sorties matérialisées et les refus de politique.
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ Les premiers contrats stabilisés sont volontairement minimaux :
|
||||
| `CoreInnerInstructionInsert` | Instruction CPI résolue avec parent, chemin et hash de payload. |
|
||||
| `CoreLogInsert` | Log ordonné avec rattachement prudent et hash de texte. |
|
||||
| `CoreBalanceChangeInsert` | Delta SOL ou token exact, déterministe et lié au compte résolu. |
|
||||
| `CoreInstructionReplayInput` | Instruction avec contexte extrait, dont les instructions outer ordonnées depuis le contrat `2`, pour les décodeurs. |
|
||||
| `MdCoreInstructionReplayInput` | Instruction avec contexte extrait, dont les instructions outer ordonnées depuis le contrat `2`, pour les décodeurs. |
|
||||
| `CoreInstructionReplayFilter` | Filtre de sélection des instructions à traiter ou rejouer. |
|
||||
| `CoreInstructionLifecycleMark` | Marquage d'état pour une instruction normalisée. |
|
||||
| `CoreInstructionProcessingState` | État opérationnel d'une instruction pour replay partiel. |
|
||||
@@ -181,12 +181,12 @@ kb_sol_ops_processing_ledger
|
||||
|
||||
Le replay opérationnel doit pouvoir cibler `CoreInstructionRow`, pas seulement `CoreTransactionRow`. Cela permet à un décodeur de demander uniquement les instructions `Pending`, `Failed` ou `ReplayRequested`, filtrées par `program_id` et plage de slots.
|
||||
|
||||
Le décodage réel doit ensuite recevoir `CoreInstructionReplayInput`, c'est-à-dire une instruction avec son contexte extrait : comptes résolus, inner instructions, logs, balances et erreur de transaction. Cette décision prépare les futures tables `kb_sol_core_instructions`, `kb_sol_core_logs`, `kb_sol_core_balance_changes` et `kb_sol_ops_processing_ledger` sans figer encore leur SQL exact.
|
||||
Le décodage réel doit ensuite recevoir `MdCoreInstructionReplayInput`, c'est-à-dire une instruction avec son contexte extrait : comptes résolus, inner instructions, logs, balances et erreur de transaction. Cette décision prépare les futures tables `kb_sol_core_instructions`, `kb_sol_core_logs`, `kb_sol_core_balance_changes` et `kb_sol_ops_processing_ledger` sans figer encore leur SQL exact.
|
||||
|
||||
|
||||
## Extension `0.2.4`
|
||||
|
||||
`0.2.4` rend les contrats core effectivement utilisés par `kb_store_pg`. Le replay reste planifié depuis `CoreInstructionRow`, mais les décodeurs reçoivent `CoreInstructionReplayInput` avec account keys, inner instructions, logs et balance changes.
|
||||
`0.2.4` rend les contrats core effectivement utilisés par `kb_store_pg`. Le replay reste planifié depuis `CoreInstructionRow`, mais les décodeurs reçoivent `MdCoreInstructionReplayInput` avec account keys, inner instructions, logs et balance changes.
|
||||
|
||||
Le champ `balance_change_index` est ajouté au contrat `CoreBalanceChangeInsert` afin de dédupliquer les balance changes par ordre d'extraction dans une transaction.
|
||||
|
||||
@@ -217,6 +217,6 @@ La couverture machine-readable est portée par `DecodeCoverageDeclarationInsert`
|
||||
|
||||
## Contrat contextualisé `2`
|
||||
|
||||
Depuis `0.4.1-pre.014`, `CoreInstructionReplayInput` transporte `outer_instructions_json`, obligatoirement un tableau JSON. Chaque entrée représente une instruction outer avec `instructionIndex`, `instructionPath`, `programId`, `payloadJson` et `payloadHash`. La liste inclut l’instruction cible et conserve l’ordre numérique du message. Ce champ participe à la sérialisation déterministe et donc au hash de replay.
|
||||
Depuis `0.4.1-pre.014`, `MdCoreInstructionReplayInput` transporte `outer_instructions_json`, obligatoirement un tableau JSON. Chaque entrée représente une instruction outer avec `instructionIndex`, `instructionPath`, `programId`, `payloadJson` et `payloadHash`. La liste inclut l’instruction cible et conserve l’ordre numérique du message. Ce champ participe à la sérialisation déterministe et donc au hash de replay.
|
||||
|
||||
Ce changement est purement contractuel : il ne requiert aucune migration SQL et ne modifie pas les garanties d’idempotence ou de rollback des stores.
|
||||
|
||||
@@ -193,7 +193,7 @@ Le repository `CoreTransactionStore` est implémenté pour :
|
||||
- insérer les logs ordonnés ;
|
||||
- insérer les balance changes ;
|
||||
- lister les instructions à rejouer ;
|
||||
- construire `CoreInstructionReplayInput` avec contexte, dont toutes les instructions outer de la signature ordonnées par index numérique ;
|
||||
- construire `MdCoreInstructionReplayInput` avec contexte, dont toutes les instructions outer de la signature ordonnées par index numérique ;
|
||||
- marquer le lifecycle d'une instruction.
|
||||
|
||||
## Baseline canonique `0.3.1`
|
||||
|
||||
@@ -21,7 +21,7 @@ Ajouter uniquement l'infrastructure PostgreSQL :
|
||||
- diagnostic du schema courant ;
|
||||
- tests offline autant que possible.
|
||||
|
||||
Ne pas créer encore les tables Solana finales. Les premières tables réelles restent prévues pour `0.2.3` et `0.2.4`. Les migrations doivent cependant rester compatibles avec les contrats `CoreInstructionReplayInput`, `CoreLogInsert`, `CoreAccountKeyInsert` et `CoreBalanceChangeInsert`.
|
||||
Ne pas créer encore les tables Solana finales. Les premières tables réelles restent prévues pour `0.2.3` et `0.2.4`. Les migrations doivent cependant rester compatibles avec les contrats `MdCoreInstructionReplayInput`, `CoreLogInsert`, `CoreAccountKeyInsert` et `CoreBalanceChangeInsert`.
|
||||
|
||||
## Règle PostgreSQL obligatoire
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@ Le contrat de décodage doit fournir au minimum :
|
||||
- changements de balances pertinents ;
|
||||
- version du contrat core.
|
||||
|
||||
Réutiliser ou faire évoluer `CoreInstructionReplayInput` au lieu de recréer un modèle parallèle par décodeur.
|
||||
Réutiliser ou faire évoluer `MdCoreInstructionReplayInput` au lieu de recréer un modèle parallèle par décodeur.
|
||||
|
||||
### Transactions échouées
|
||||
|
||||
|
||||
@@ -103,7 +103,7 @@ Respecter strictement :
|
||||
- aucun `bincode` direct ;
|
||||
- aucune logique métier lourde dans `kb_app_demo` ;
|
||||
- `CHANGELOG.md` inchangé avant validation complète du jalon ;
|
||||
- `TRACING_TARGET` canonique dans `src/constants.rs` pour toute crate opérationnelle ;
|
||||
- `DC_METADATA_MTM_TRACING_TARGET` canonique dans `src/constants.rs` pour toute crate opérationnelle ;
|
||||
- aucune valeur JSON Tauri exportée en `bigint` lorsqu'elle traverse `invoke`, `emit` ou `JSON.stringify`.
|
||||
|
||||
## 7. Audit préalable obligatoire
|
||||
|
||||
@@ -125,7 +125,7 @@ Respecter strictement :
|
||||
- aucun `bincode` direct ;
|
||||
- aucune logique métier lourde dans `kb_app_demo` ;
|
||||
- `CHANGELOG.md` inchangé avant validation complète de `0.4.4` ;
|
||||
- `TRACING_TARGET` canonique dans `src/constants.rs` pour toute crate opérationnelle ;
|
||||
- `DC_METADATA_MTM_TRACING_TARGET` canonique dans `src/constants.rs` pour toute crate opérationnelle ;
|
||||
- aucune valeur JSON Tauri exportée en `bigint` lorsqu’elle traverse `invoke`, `emit` ou `JSON.stringify` ;
|
||||
- montants on-chain bruts sérialisés sans perte, sous forme de chaîne à la frontière Tauri si nécessaire.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user