0.1.0

migration/khadhroony-bot2-reference/kb_materializer_token_accounts/README.md

@@ -0,0 +1,29 @@
+<!-- file: kb_materializer_token_accounts/README.md -->
+<!-- version: 4 -->
+
+# kb_materializer_token_accounts
+
+Ce crate matérialise les mutations instructionnelles commitées du programme SPL Token classique et le lifecycle d'adresses associées ATA dans le journal générique `kb_sol_mat_events`.
+
+## Projections actives
+
+- initialisations de mint et de compte ;
+- transferts, approvals/revocations, mint et burn ;
+- freeze/thaw et close ;
+- `SyncNative`, `InitializeImmutableOwner`, `WithdrawExcessLamports` et `UnwrapLamports`.
+- `ata_created` pour `Create` ;
+- `ata_created_or_reused_idempotently` pour `CreateIdempotent`, sans inventer laquelle des deux branches s'est produite ;
+- `nested_ata_recovered` pour `RecoverNested`, avec wallet, mints, trois ATA et Token Program classique ou Token-2022.
+
+Chaque sortie conserve signature, slot, chemin, comptes, autorité, mint lorsqu'il est explicite, montant brut en chaîne et decimals présents dans le wire. Le matérialiseur utilise `SuccessfulCommittedOnly` et refuse toute transaction échouée.
+
+## Limites et déduplication
+
+La projection décrit une mutation d'instruction, jamais le snapshot final du compte. Elle ne recopie pas les changements de balances core. Le parent ATA possède uniquement le lifecycle de l'adresse associée ; les CPI SPL Token conservent la propriété exclusive des initialisations, transferts et fermetures de comptes. Le parent `Batch`, les conversions amount/UI amount, `set_authority` et la configuration multisig sont laissés respectivement aux enfants, au decode et au matérialiseur admin.
+
+## Corpus validé
+
+Le replay Mainnet du 15 juillet 2026 a produit 362 sorties `token_account` et neuf constats `risk`
+depuis 370 instructions décodées. Les huit refus de matérialisation correspondent exactement à des
+transactions échouées ; aucune sortie non commitée, aucun parent `Batch` dupliqué et aucun faux frais
+classique n'ont été persistés. Un second replay sans force a sélectionné zéro entrée.