khadhroony-bot3/migration/khadhroony-bot2-reference/kb_decoder_spl_memo

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.

DcSplMemoDecoder implémente le contrat contextualisé DcApiInstructionDecoder. La reconnaissance est exacte pour ces trois IDs et incompatible avec tout autre programme. L’adaptateur historique DcApiProtocolDecoder 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.