khadhroony-bot3/docs/MATERIALIZATIONS.md

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.