v0.1.0-pre.064-065

olddocs/archivekbot2/kb_decoder_spl_memo/README.md

@@ -0,0 +1,55 @@
+<!-- file: kb_decoder_spl_memo/README.md -->
+<!-- version: 4 -->
+
+# kb_decoder_spl_memo
+
+Ce crate décode les programmes SPL Memo v1, v3 et v4 depuis l’instruction core contextualisée.
+
+## Surface exacte
+
+- v1 : `Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo` ;
+- v3 : `MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr` ;
+- v4 : `Memo4c2pN8afCj432Lb7RMVKi9PbQnnW7ewFFaV3oAH`.
+
+`SplMemoDecoder` implémente le contrat contextualisé `InstructionDecoder`. La reconnaissance est exacte pour ces trois IDs et incompatible avec tout autre programme. L’adaptateur historique `ProtocolDecoder` déclare `Yes` pour ces IDs, mais ne fabrique pas d’événement sans instruction contextualisée.
+
+## Contrat décodé
+
+Le payload Memo est la totalité des octets de l’instruction, sans discriminator ni préfixe de longueur. Le décodeur conserve :
+
+- la génération et le Program ID exacts ;
+- le texte complet lorsque l’UTF‑8 est valide ;
+- la longueur en octets, le SHA-256 et un préfixe hexadécimal borné à 32 octets ;
+- tous les comptes dans leur ordre, y compris les doublons, avec position, index, pubkey, signer et writable ;
+- les signataires observés et les comptes non signers ;
+- le chemin outer/inner, le succès de transaction et l’état committed ;
+- les validations syntaxiques et le statut de preuve runtime.
+
+Le décodeur accepte au maximum 4 096 octets décodés. Cette limite protège le replay contre un payload core anormal tout en dépassant la taille pratique d’une instruction contenue dans une transaction Solana actuelle. Dans cette borne, le texte valide est conservé sans troncature.
+
+Les événements sont :
+
+- `add_memo` pour une transaction réussie dont le contrat est valide ;
+- `memo_intent` pour un payload lisible dans une transaction échouée ;
+- `invalid_memo_attempt` pour un UTF‑8 invalide ou un compte non signer lorsque la génération l’exige.
+
+Une transaction échouée n’est jamais marquée committed et son statut runtime reste `not_proven_transaction_failed`, même lorsque l’analyse statique des octets et comptes est valide.
+
+## Différences de génération
+
+Memo v1 valide l’UTF‑8 et ignore les comptes. Memo v3 et v4 parcourent tous les comptes fournis et échouent si l’un d’eux n’est pas signer ; zéro compte reste valide. Les trois générations partagent le même wire de données brutes, mais le décodeur conserve des surfaces et règles séparées.
+
+La matrice normative et les références officielles sont dans `docs/SPL_MEMO_MATRIX.json`.
+
+Le corpus réel couvre les trois générations sur Mainnet. La validation opérateur ajoute trois signatures v4 Devnet confirmées, toutes décodées comme `add_memo` outer au path `0`, avec compte wallet signer readonly, sans échec de décodage. v1 et v3 ne sont pas prétendues déployées sur Devnet : leur couverture réelle reste assurée par le replay Mainnet et leur construction reste soumise à simulation avant tout envoi.
+
+## Projection
+
+`kb_materializer_transaction_annotations` projette uniquement les `add_memo` réussis et commités dans la famille dédiée `TransactionAnnotation`. Les intentions échouées et tentatives invalides restent consultables dans le decode sans devenir des annotations réussies. Les comptes complets, flags writable, diagnostics, préfixes hexadécimaux et preuves restent volontairement dans l’événement décodé ; la projection conserve le texte, la longueur, le hash et les signataires utiles à la recherche et à la corrélation.
+
+## Règles locales
+
+- Les commentaires de code restent en anglais.
+- La documentation Markdown reste en français.
+- Les exports publics sont contrôlés depuis `lib.rs`.
+- Les erreurs de rétention core, de base64, de taille ou de résolution de comptes produisent un résultat `Failed` borné, jamais un faux Memo.