48 lines
4.0 KiB
Markdown
48 lines
4.0 KiB
Markdown
<!-- file: kb_materializer_transaction_annotations/README.md -->
|
||
<!-- version: 4 -->
|
||
|
||
# kb_materializer_transaction_annotations
|
||
|
||
Ce crate fournit une projection réutilisable d’annotations de transaction. La première surface active est SPL Memo v1, v3 et v4 ; le domaine n’est volontairement pas fusionné avec metadata, admin, lifecycle ou compliance audit.
|
||
|
||
## Projection Memo
|
||
|
||
Le matérialiseur accepte uniquement les observations `spl_memo` dont le Program ID, la surface et l’entrée correspondent exactement. `add_memo`, `memo_intent` et `invalid_memo_attempt` sont reconnus afin que la politique commune puisse enregistrer un refus explicite, mais seule une observation `add_memo` réussie et commitée produit une sortie.
|
||
|
||
La sortie `TransactionAnnotation` conserve :
|
||
|
||
- signature, slot et chemin d’instruction outer/inner ;
|
||
- génération et Program ID exacts ;
|
||
- texte UTF‑8 complet dans la borne de 4 096 octets ;
|
||
- longueur et SHA-256 du payload ;
|
||
- signataires exigés, observés et réellement vérifiés par la génération ;
|
||
- état committed, version de projection et provenance du matérialiseur ;
|
||
- clé d’idempotence déterministe fondée sur signature, chemin, Program ID et hash.
|
||
|
||
Pour v1, les comptes signers restent observables mais la liste `verified` est vide, car le runtime historique ne les vérifie pas. Pour v3/v4, une projection commitée exige l’égalité ordonnée entre signataires requis et observés, doublons compris.
|
||
|
||
## Persistance et replay
|
||
|
||
La sortie utilise le store commun `kb_sol_mat_events` avec la famille `transaction_annotation`. Aucune migration SQL supplémentaire n’est nécessaire et les événements decode/core ne sont pas dupliqués. Le ledger commun assure :
|
||
|
||
- replay identique et même version : skip ;
|
||
- force replay : remplacement atomique des sorties appartenant à la version ciblée ;
|
||
- changement de version : identité de processor distincte et déterministe.
|
||
|
||
Les transactions échouées, observations non commitées, UTF‑8 invalides et validations de signataires invalides restent uniquement dans `kb_sol_decode_events`. Les comptes complets, flags writable, préfixes diagnostics, erreurs UTF‑8 et preuves détaillées restent également dans l’événement décodé ; la projection ne conserve que les champs utiles à la consultation d’annotations.
|
||
|
||
## Consultation
|
||
|
||
La fenêtre `demo_decode_replay` affiche les sorties comme un journal d’annotations, et non comme une série OHLC : slot, signature, instruction path, génération, texte, longueur, signataires vérifiés, hash et provenance. La lecture passe par le contrat borné `DecodePipelineStore::list_materialized_events`, filtré exactement sur le processor `transaction_annotations` et la famille `transaction_annotation` ; aucun SQL libre ni payload JSON arbitraire ne traverse l’UI.
|
||
|
||
La démo d’exécution Memo v4 réutilise ce même contrat de lecture pour vérifier la projection après confirmation. Trois transactions Devnet réelles ont chacune produit exactement une annotation ; le second replay a été `skipped` sans sortie supplémentaire ni refus. Cette projection reste un journal consultable et corrélable, pas une agrégation temporelle de type OHLC.
|
||
|
||
Le parcours Mainnet du 14 juillet 2026 a acquis puis extrait 300 transactions réelles, 100 par Program ID. Le replay a décodé 102 instructions v1, 439 v3 et 100 v4 sans unmatched ni échec de décodage. La projection a produit respectivement 69, 422 et 100 annotations ; les 33 refus v1 et 17 refus v3 correspondaient aux intentions issues de transactions échouées. Un second replay v3 non forcé a sélectionné zéro entrée, validant le skip idempotent du ledger. Les campagnes forcées v3/v4 ont également reproduit les mêmes nombres de sorties.
|
||
|
||
## Règles locales
|
||
|
||
- `SuccessfulCommittedOnly` est appliqué avant toute sortie.
|
||
- Un payload décodé incohérent échoue fermé avec un diagnostic stable.
|
||
- Le target tracing canonique est `kb_materializer_transaction_annotations`.
|
||
- Aucun log ne contient de clé privée ni de texte Memo complet.
|