khadhroony-bot3/docs/MATERIALIZATIONS.md

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

# 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 portées dans `kb-lib`

`kb_lib::LifecycleMaterializer` 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_lib::AdminMaterializer` produit des sorties `Admin` pour les assignations System, les écritures Config opaques et les changements d’autorité Loader. `kb_lib::ComplianceAuditMaterializer` produit des sorties `ComplianceAudit` pour les écritures/copies de bytecode Loader. `kb_lib::StakingMaterializer` 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.

Les implémentations résident dans des modules privés et sont réexportées uniquement à la racine de `kb-lib`. Les identités de processor historiques restent stables pour les replays ; les targets de tracing utilisent la hiérarchie consolidée `kb-lib.materializer.*`.

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é.

## Projections SPL et Metaplex portées

- `MtTransactionAnnotationMaterializer` accepte uniquement les observations Memo exactes, réussies et commitées, puis produit une annotation idempotente bornée avec texte, hash, génération et signataires vérifiés.
- `MtTokenAccountsMaterializer` projette les mutations SPL Token classique et Token‑2022, possède le lifecycle ATA et peut produire un snapshot borné Mint/Account/Multisig Token‑2022 à partir de l’état parsé.
- `MtFeesMaterializer` projette les instructions et snapshots de frais Token‑2022 publics ou confidentiels. Les blobs confidentiels restent opaques et `confidentialValuesDecrypted` demeure faux.
- `MtRiskMaterializer` produit uniquement des faits structurels SPL Token/ATA : délégation, freeze/thaw, autorités révoquées, multisig faible et récupération d’ATA imbriquée. Aucun score arbitraire n’est inventé.
- `MtMetadataMaterializer` projette les metadata incorporées Token‑2022 et les comptes Metaplex canoniques, avec provenance et lifecycle explicites. `externalUriFetched` reste faux.

Le registre ElGamal ne possède pas un matérialiseur autonome : ses snapshots administratifs sont la responsabilité de `MtAdminMaterializer`. Le fetch HTTP/IPFS/Arweave des URI est off-chain et reste réservé à une future crate dédiée.

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

- `nft` : NFT classiques, programmables et compressés.
- `metadata` avancée : fetch off-chain borné, réconciliation de provenance et historique des changements.
- `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.