khadhroony-bot3/migration/khadhroony-bot2-reference/docs/MATERIALIZATIONS.md

<!-- file: docs/MATERIALIZATIONS.md -->
<!-- version: 6 -->

# Catalogue des matérialisations

Les matérialisations transforment des événements décodés en événements métier exploitables par la base de données, les validations, les agrégations et les futurs signaux de stratégie.

## Matérialisations prioritaires

- `trade` : swaps, buys, sells, fills et conversions entre actifs.
- `liquidity` : dépôts, retraits, ajout ou retrait de liquidité, bootstrap de pool.
- `lifecycle` : création, initialisation, migration, fermeture ou changement d'état d'un pool, marché, compte ou vault.
- `fee` : collecte, claim, sweep, buyback, mise à jour de configuration de frais.
- `admin` : changement d'autorité, update de config, pause, unpause, transfert de rôle.
- `token_account` : création ATA, transfert, mint, burn, close account, approve, revoke.
- `pool_state` : snapshots de réserves, ticks, bins, prix, liquidité active ou virtual reserves.
- `orderbook` : place order, cancel order, fill, settle funds, consume events.
- `reward` : émission, claim, distribution, farming, incentives.
- `risk` : signaux dérivés à partir des événements admin, liquidité, metadata, authority ou anomalies.

## Projections natives actives dans `0.4.1`

`kb_materializer_lifecycle` produit des événements lifecycle idempotents à partir d'observations exactes, réussies et commitées :

| Domaine              | Sortie stable                              | Entrées couvertes                                                                                            |
|----------------------|--------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| Address Lookup Table | `address_lookup_table:<operation>:0`       | create, freeze, extend, deactivate, close                                                                    |
| Program loaders      | `program_loader:<surface>:<operation>:0`   | finalize immuable, initialize/deploy/upgrade/close/extend upgradeable, set length/deploy/retract/finalize v4 |
| Feature Gate         | `feature_gate:revoke_pending_activation:0` | revoke pending activation                                                                                    |
| Comptes System       | `system_account:<operation>:0`             | create, create with seed, create allow prefund, allocate, allocate with seed                                 |
| Durable nonce System | `durable_nonce_account:<operation>:0`      | initialize, advance, authorize, upgrade, withdraw                                                            |
| Contexte ZK ElGamal  | `zk_proof_context:<operation>:0`           | initialisation demandée après vérification réussie, fermeture                                                |
| Rapport Slashing     | `slashing_violation_report:<operation>:0`  | initialisation après preuve duplicate block acceptée, fermeture après rétention                              |

La famille décodée n'impose pas à elle seule la famille matérialisée. `authorize_nonce_account` est un événement `Admin`, tandis qu'une vérification ZK ElGamal est un événement `Audit`; ces observations ne produisent une sortie `Lifecycle` que lorsque leur mutation durable exacte est reconnue. Une transaction échouée ou non commitée est toujours refusée.

`kb_materializer_admin` produit des sorties `Admin` pour les assignations System, les écritures Config opaques et les changements d’autorité Loader. `kb_materializer_compliance_audit` produit des sorties `ComplianceAudit` pour les écritures/copies de bytecode Loader. `kb_materializer_staking` produit les projections instructionnelles Stake/Vote commitées : comptes stake/vote, autorités, lockup, délégation, vote state, retraits et dépôt de rewards. Les données complètes ne sont jamais recopiées : seules les clés, autorités, offsets, tailles, hashes, préfixes et paramètres bornés disponibles sont conservés.

Le retrait d'un nonce account conserve une sémantique conditionnelle : le runtime ferme le compte uniquement lorsque la totalité du solde est retirée. La projection décrit l'opération commitée et ne prétend pas reconstruire l'état final transactionnel du compte. Les deltas SOL restent la responsabilité du graphe core.

Une preuve ZK n'est jamais matérialisée. Seul le lifecycle du compte de contexte est projeté lorsqu'il existe. Un rapport Slashing conserve le signal de violation et son lifecycle, mais pas le contenu du compte de preuve externe ; `penaltyAppliedByProgram` reste faux car le programme ne retire pas lui-même du stake. L'ancien ZK Token Proof Program reste en decode/audit, car le runtime actuel est sans effet et aucun historique mainnet fiable n'a été observé.

## Matérialisations spécialisées à prévoir

- `nft` : NFT classiques, programmables et compressés.
- `metadata` : metadata Metaplex, creators, collection, update authority, URI et symbol.
- `oracle` : prix, publisher, confidence, staleness et sources d'oracle.
- `lending` : borrow, repay, collateral, liquidation et health factor.
- `staking` avancé : snapshots de comptes Stake/Vote avant/après, activation par epoch, crédits Vote cumulés et réconciliation avec sysvars.
- `governance` : proposal, vote, execute et update de realm/config.
- `bridge` : lock, mint wrapped asset, burn, redeem et message verification.
- `perpetuals` : position, funding, liquidation, collateral et PnL.
- `vault` : share mint/burn, deposit, withdraw, rebalance et fee collection.
- `routing` : route, route leg, quote, slippage, aggregator hop.
- `compliance_audit` : événements d'audit non directement matérialisables en trading.
- `token_metadata_risk` : signaux de risque issus des métadonnées de tokens, par exemple autorité mutable, creators suspects, symbol/URI incohérents ou changements de metadata.

## Projections natives encore à terminer avant clôture

Toutes les sémantiques matérialisables ne sont pas encore projetées. Les lots restants sont explicites :

- Compute Budget : profil transactionnel agrégé regroupant toutes les instructions Compute Budget du message.

Les précompiles de signature et les preuves ZK sans contexte restent des observations d'audit déjà suffisantes. Une projection supplémentaire n'est justifiée que si un consommateur `compliance_audit` exige une table dédiée. L'ancien ZK Token Proof no-op reste sans matérialisation.

## Règle de conception

Une matérialisation spécialisée ne doit être ajoutée que si la table générique ne suffit pas pour représenter correctement la sémantique du protocole. Le modèle commun reste prioritaire, puis les tables spécialisées complètent ce modèle. Chaque projection doit posséder une identité stable, un état cible explicite, une politique d'idempotence et une règle documentée pour les transactions échouées.