khadhroony-bot3/kb-lib

kb-lib

kb-lib regroupe les modèles partagés et les composants de décodage, matérialisation et exécution de khadhroony-bot3. Les composants restent séparés par modules privés et sont exposés par la façade unique kb-lib/src/lib.rs.

Décodeur Solana Core

DcSolanaCoreDecoder est le premier décodeur concret porté depuis bot2. Il implémente DcApiInstructionDecoder et DcApiProtocolDecoder sans dépendre de PostgreSQL, du RPC, de Tauri ou du wallet.

Il couvre les 18 surfaces natives suivantes :

• System Program ;
• Compute Budget ;
• Address Lookup Table ;
• Config et Feature Gate ;
• Vote et Stake ;
• loaders natifs, BPF historiques, upgradeable et Loader v4 ;
• précompiles Ed25519, secp256k1 et secp256r1 ;
• Slashing ;
• ZK ElGamal Proof et l’ancien ZK Token Proof.

La matrice docs/NATIVE_SOLANA_DECODER_MATRIX.json reste la source machine-readable de la couverture. Les instructions inconnues, tronquées, historiques ou issues d’une transaction échouée conservent les statuts et diagnostics explicites définis par les contrats communs.

Décodeur SPL Memo

DcSplMemoDecoder couvre exactement les générations v1, v3 et v4. Le payload est lu comme un message brut sans discriminator, borné à 4 096 octets, puis projeté avec son texte UTF-8 complet, sa longueur, son SHA-256, les comptes ordonnés et le statut de commit.

Memo v1 ignore les comptes lors de la validation runtime. Memo v3 et v4 exigent que chaque compte fourni soit signer. Les transactions échouées restent des intentions non commitées et les payloads UTF-8 invalides ou signatures manquantes deviennent des tentatives invalides explicites. La matrice normative est docs/SPL_MEMO_MATRIX.json.

Décodeur SPL Token classique

DcSplTokenDecoder couvre exclusivement le Program ID classique TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA. Il publie 28 déclarations de couverture pour les tags 0..24, 38, 45 et 255, y compris les variantes historiques, checked, WithdrawExcessLamports, UnwrapLamports et Batch.

Le parseur conserve les montants bruts sans perte, les comptes dans leur ordre d’origine, les formes d’autorité simple ou multisig, les suffixes runtime et les chemins outer/inner. Une transaction échouée reste une intention non commitée. Batch est borné à 64 enfants, 512 comptes cumulés et interdit les batches imbriqués. Le décodeur n’invente ni mint, ni decimals, ni état final ; les validations M/N, soldes et autorités existantes restent stateful. La matrice normative est docs/SPL_TOKEN_MATRIX.json.

Décodeur SPL Associated Token Account

DcSplAssociatedTokenAccountDecoder couvre exclusivement ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL. Il reconnaît les trois variantes publiées Create, CreateIdempotent et RecoverNested, ainsi que l’encodage historique vide de Create.

Le décodeur conserve les comptes dans leur ordre original, leurs flags, doublons, chemins outer/inner et le statut de transaction. Il dérive les PDA avec l’ordre canonique [wallet, token_program, mint], conserve simultanément l’adresse observée et l’adresse attendue, puis expose tout écart comme diagnostic. SPL Token classique et Token‑2022 sont distingués par leur Program ID sans reconstruire leur état ni interpréter leurs extensions. La matrice normative est docs/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json.

Décodeur SPL Token‑2022

DcSplToken2022Decoder couvre exclusivement TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb. Il conserve les 48 enveloppes de premier niveau, les sous-instructions d’extensions dont le wire est officiellement identifiable, les interfaces Token Metadata et Token Group exécutées directement par Token‑2022, ainsi que Batch sans batch imbriqué.

Le décodeur borne les payloads, les chaînes de metadata, le nombre d’enfants et les comptes cumulés. Les comptes, autorités, offsets de preuve, suffixes et chemins outer/inner restent ordonnés et exacts. Une transaction échouée produit une intention non commitée. Le parseur public decoder_spl_token2022_parse_token2022_state() distingue Mint, Account et Multisig, conserve la base exacte et expose les entrées TLV ordonnées sans inventer l’état d’un programme externe pointé. La matrice normative est docs/SPL_TOKEN2022_MATRIX.json.

Décodeur du registre ElGamal

DcSplElgamalRegistryDecoder couvre le programme indépendant regVYJW7tcT8zipN5YiBvHsvR5jXW1uLFxaHSbugABg. Il décode exactement CreateRegistry et UpdateRegistry, conserve l’offset relatif de preuve et ne prétend jamais vérifier la preuve ZK. decoder_spl_elgamal_registry_parse_elgamal_registry_state() exige exactement 64 octets et restitue le wallet propriétaire, la clé publique ElGamal et le wire complet. La matrice normative est docs/SPL_ELGAMAL_REGISTRY_MATRIX.json.

Décodeur Metaplex Token Metadata

DcMetadataMetaplexTokenMetadataDecoder couvre exclusivement metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s. Il inventorie exactement les 58 discriminateurs 0..=57, conserve les arguments Borsh, les comptes positionnels, les placeholders optionnels, les chemins outer/CPI et les transactions échouées comme intentions non commitées.

La façade kb_lib expose aussi les parseurs bornés des 15 variantes Key 0..=14 : Metadata, Edition et Master Edition, Edition Marker V1/V2, Token Record, records de délégation et d’autorité, Token Owned Escrow et Reservation List historiques. Chaque parseur vérifie l’owner, le PDA, le bump, la longueur et les suffixes avant projection. Les comptes historiques gardent une provenance et un lifecycle matérialisables, mais une politique d’exécution définitivement interdite. La matrice normative est docs/METAPLEX_TOKEN_METADATA_MATRIX.json.

API publique utile

• MtApiEventMaterializer, MtApiMaterializerIdentity, MtApiMaterializationTransactionPolicy, MtApiMaterializerExecutionResult et MtApiMaterializedOutput : contrat complet utilisable par un matérialiseur interne ou externe ;
• MtLifecycleMaterializer, MtAdminMaterializer, MtComplianceAuditMaterializer et MtStakingMaterializer : matérialisateurs Solana natifs concrets ;
• materializer_admin_materialize_token2022_state_snapshots() et materializer_admin_materialize_elgamal_registry_state_snapshot() : projections stateful d’administration déjà exposées ;
• DcSolanaCoreDecoder : décodeur concret natif ;
• DcSplMemoDecoder : décodeur exact des trois générations SPL Memo ;
• DcSplTokenDecoder : décodeur exact du programme SPL Token classique ;
• DcSplAssociatedTokenAccountDecoder : décodeur exact du programme Associated Token Account ;
• DcSplToken2022Decoder : décodeur exact des instructions Token‑2022 ;
• DcToken2022State, DcToken2022StateKind, DcToken2022TlvEntry et decoder_spl_token2022_token2022_state() : API publique de lecture d’état Token‑2022 ;
• DcSplElgamalRegistryDecoder, DcSplElGamalRegistryState et decoder_spl_elgamal_registry_parse_elgamal_registry_state() : API publique du registre ElGamal ;
• DcMetadataMetaplexTokenMetadataDecoder : décodeur exact du programme Metaplex Token Metadata ;
• les fonctions decoder_metadata_metaplex_token_metadata_* et les types DcMetadataMtm* : parseurs et snapshots publics des comptes Metaplex ;
• les 98 types réservés Dc*Decoder : squelettes compatibles avec DcApiProtocolDecoder, exposant 97 Program IDs enregistrés et la frontière générique Anchor sans Program ID ;
• DcApiInstructionDecoder : contrat de reconnaissance, couverture et décodage contextualisé ;
• DcApiProtocolDecoder : contrat de compatibilité avec les observations historiques ;
• ExSolanaCoreExecutor, ExSolanaCoreExecutionIntent et ExSolanaCoreOperation : exécuteur natif fonctionnel et contrat typé couvrant 109 opérations ;
• les constantes EX_SOLANA_CORE_*_OPERATION : codes stables des opérations System, Compute Budget, ALT, précompiles, Config, Feature, Slashing, ZK ElGamal, Stake, Vote et Loaders ;
• ExSafetyChecker, ExSafetyDecision, ExSafetyEvaluation et ExSafetyViolation : garde-fous communs avant simulation, signature et envoi ;
• ExSplMemoExecutor, ExSplMemoExecutionIntent et ExSplMemoOperation : exécuteur SPL Memo v4 fonctionnel, avec v1/v3 explicitement decode-only ;
• ExApiTypedInstructionExecutor et ExApiInstructionExecutor : contrat typé actuel et pont JSON historique de l’exécution ;
• MdCoreInstructionReplayInput : input source-neutral produit par l’extraction core ;
• DcApiDecoderExecutionResult, DcApiDecoderRecognition et DcApiDecoderCoverageDeclaration : résultats typés du pipeline ;
• modèles canoniques et nomenclature réexportés depuis la façade.

Les helpers, constantes wire et types intermédiaires de chaque composant restent internes. Leurs noms sont préfixés au niveau de la façade interne afin d’éviter les collisions lors de la fusion des anciens crates.

Exemple

let decoder = kb_lib::DcSolanaCoreDecoder;
let recognition = kb_lib::DcApiInstructionDecoder::recognize(&decoder, &input);

L’appel de décodage complet utilise DcApiInstructionDecoder::decode après une reconnaissance compatible. Le pipeline demeure responsable de la sélection du décodeur et de la persistance du résultat.

Frontières

• kb-lib ne dépend jamais de kb-store.
• Les décodeurs ne lisent pas un état RPC courant pour reconstruire une transaction historique.
• Une transaction échouée peut produire une intention structurée, jamais une mutation commitée.
• Un matérialiseur externe dépend uniquement des contrats et modèles publics de kb-lib, jamais d’un décodeur concret.
• Les squelettes réservés répondent uniquement Maybe pour leur Program ID et retournent une liste vide ; ils ne prétendent pas décoder une surface avant son port fonctionnel.
• Les 102 squelettes d’exécuteurs encore réservés annoncent uniquement Maybe pour leurs Program IDs enregistrés et construisent un plan réservé à zéro instruction.
• ExSolanaCoreExecutor annonce uniquement des capacités exactes Supported ou Unsupported et ne signe, n’envoie ni ne simule aucune transaction.
• ExSafetyChecker évalue les plans et résultats de simulation sans effectuer lui-même d’appel RPC, de signature ou d’envoi.
• ExSplMemoExecutor construit uniquement des plans ; il ne signe, n’envoie ni ne simule aucune transaction.
• Les exécuteurs fonctionnels sont portés dans des tranches séparées, sans dépendre des décodeurs.