khadhroony-bot3/ks-lib

ks-lib

ks-lib est la bibliothèque fonctionnelle consolidée de khadhroony-bot3. Elle fournit les modèles, décodeurs, matérialisateurs, exécuteurs et contrats de sécurité indépendants du transport, du stockage et de l’interface utilisateur.

Périmètre

La crate couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et Metaplex Token Metadata. Elle expose également les modèles wire bornés, les décodeurs de comptes Buffer et Metadata, le décodeur contextualisé des neuf instructions stables et la matérialisation exhaustive de Solana Program Metadata.

Pour Solana Program Metadata, la surface publique fondatrice comprend :

• les tailles fixes officielles des headers, seeds et références externes ;
• les enums fermées de discriminateur, encodage, compression, format et source ;
• le seed brut de 16 octets avec helpers UTF-8 bornés ;
• les données directes, URL et références vers un autre compte sans résolution off-chain ;
• les cinq erreurs custom officielles et les erreurs de conversion fail-closed ;
• les snapshots bornés Buffer et Metadata, avec validation du propriétaire, des PDA metadata, des longueurs logiques et des trois sources de données ;
• une politique explicite où les octets situés après data_length sont conservés comme capacité allouée et jamais assimilés au contenu logique ;
• les neuf instructions stables Write, Initialize, SetAuthority, SetData, SetImmutable, Trim, Close, Allocate et Extend ;
• les formes runtime actuelles non produites par le SDK, notamment SetData sans remplacement de données et les suffixes ignorés de SetImmutable, Trim et Close ;
• une frontière historique où l’ancien nom pré-stable WithdrawExcessLamports du tag 5 reste une provenance de Trim, sans dixième entrée de couverture ;
• une sélection canonical/non-canonical explicite dans les intents Initialize et Allocate, indépendante de la seule présence de ProgramData ;
• deux projections d’état autoritatives pour Buffer et Metadata, avec conservation bornée du contenu on-chain ;
• neuf faits de mutation d’instructions committées, non autoritatifs vis-à-vis de l’état final et réconciliables avec les snapshots post-exécution ;
• une classification où les neuf instructions stables sont courantes, sans opération officiellement remplacée ou obsolète à annoter Deprecated ;
• un exécuteur typé couvrant les neuf opérations, avec dérivation des PDA, wire exact, comptes ordonnés, signataires, approbation explicite des mutations dangereuses et évaluation commune par ExSafetyChecker.

Pour Metaplex Token Metadata, elle fournit :

• le décodage des 58 discriminants et des principales familles de comptes ;
• la propriété unique des faits metadata, admin, lifecycle et risk/compliance ;
• 20 opérations courantes exécutables ;
• 15 opérations obsolètes encore constructibles, exposées comme dépréciées et soumises à une approbation explicite ;
• 22 versions remplacées conservées en décodage uniquement et redirigées vers leur remplacement canonique final ;
• une frontière explicite avec Bubblegum et avec les metadata incorporées de Token-2022 ;
• un sous-module de matérialisation dédié materializer/metadata/metaplex_token_metadata, qui conserve les projections d’état déjà livrées sans modifier leurs clés ni leur sémantique persistée.

Architecture des matérialisateurs

L’arbre src/materializer suit un contrat homogène :

• une façade limitée aux déclarations de sous-modules et réexports ;
• un constants.rs propriétaire des identités, familles, surfaces, versions de projection et tracing targets ;
• un materializer.rs pour les implémentations de traits ;
• des fichiers state.rs ou account.rs uniquement lorsque la projection stateful l’exige ;
• une identité runtime kb-lib.materializer.* distincte du processorName persisté materializer.* ;
• des coquilles réservées réellement inactives sur les deux contrats legacy et contextuel.

L’inventaire audité comprend 25 composants nommés : onze matérialisateurs actifs et quatorze coquilles réservées. Les composants metadata Metaplex Token Metadata, Solana Program Metadata et Token-2022 possèdent chacun un type spécialisé, une identité propre et leurs APIs de snapshots lorsque leur état on-chain l’exige. Le détail est consigné dans l’audit de convention des matérialisateurs.

Responsabilités

• reconnaître et décoder des instructions contextualisées ;
• décoder les comptes on-chain pris en charge ;
• produire des observations et diagnostics typés ;
• matérialiser les faits stables et prouvés ;
• construire des plans d’exécution bornés ;
• déclarer les comptes, signers, coûts et confirmations nécessaires ;
• appliquer les garde-fous fail-closed avant simulation, signature ou envoi ;
• exposer des modèles indépendants du RPC, de PostgreSQL et de Tauri.

Hors périmètre

ks-lib ne sélectionne aucun endpoint, ne lit pas directement un RPC, ne persiste aucune donnée, ne gère pas les secrets de wallet et ne soumet aucune transaction.

Surface publique principale

• contrats DcApi* et décodeurs concrets Dc*Decoder ;
• parseurs de comptes et d’états bornés ;
• contrats MtApi* et matérialisateurs concrets ;
• contrats ExApi*, politiques de sécurité et exécuteurs Ex*Executor ;
• ExMetadataMetaplexTokenMetadataExecutor, ExMetaplexTokenMetadataExecutionIntent et ExMetaplexTokenMetadataOperation ;
• DcMetadataSolanaProgramMetadataDecoder, modèles DcMetadataSpm*, constantes DC_METADATA_SPM_*, fonctions decoder_metadata_solana_program_metadata_decode_*_account et helpers materializer_metadata_materialize_solana_program_metadata_*_snapshot ;
• ExMetadataSolanaProgramMetadataExecutor, ExMetadataSpmExecutionIntent, ExMetadataSpmOperation, les helpers de PDA et les constantes EX_METADATA_SPM_*_OPERATION ;
• modèles canoniques Md* réexportés par la façade.

Les exemples d’appel et invariants sont documentés dans USAGE.md.

Relations avec le workspace

• dépend de ks-core et ks-program-ids ;
• est consommée par ks-pipeline, ks-store, ks-onchain-transport, ks-pipeline-demo-scenarios et kb-app-demo-desktop ;
• ne dépend jamais de ks-store, ks-pipeline ni d’une application.

Statut et limites

La surface fonctionnelle Metaplex de la crate est achevée. Les campagnes Devnet restantes relèvent de ks-pipeline-demo-scenarios et de kb-app-demo-desktop, non d’un manque de builder dans ks-lib.

Pour Solana Program Metadata, les modèles wire, les décodeurs bornés de comptes, le décodeur contextualisé, la matérialisation des deux comptes et des neuf instructions stables, ainsi que l’exécuteur typé des neuf opérations sont actifs. Buffer accepte tout reliquat comme données allouées sans inventer de PDA stable après changement d’autorité ; Metadata valide la dérivation canonical ou non-canonical et distingue le contenu logique de la capacité ajoutée par Extend. Les instructions produisent des faits committés non autoritatifs ; les snapshots post-exécution restent la source de l’état final. Les variantes qui dépendent de l’état du compte restent des intentions wire jusqu’aux lectures stateful prévues, et aucune forme pré-stable n’est déclarée compatible réseau sans preuve de cluster.

Le registre ElGamal n’est pas déclaré validé réellement sur réseau.

Documentation

• Guide d’utilisation

• Travaux restant à réaliser

• Historique des changements

• Matrice contractuelle Metaplex

• Matrice des comptes Solana Program Metadata

• Matrice des instructions Solana Program Metadata

• Matrice de matérialisation Solana Program Metadata

• Matrice d’exécution Solana Program Metadata

• Audit de l’inventaire et de l’historique des instructions

• complétude d’exécution des cinq instructions Token-2022 Token Metadata, y compris UpdateAuthority et Emit ;