# ksp-interface-lib `ksp-interface-lib` est la façade wire officielle KSP destinée aux contrats passifs partagés par les implémentations Program Solana officielles ou externes. La crate expose uniquement des structures de représentation/admission ; elle ne possède ni transport, ni exécution, ni persistence, ni comportement métier Program. ## Ownership La crate réutilise les primitives fondamentales déjà possédées par `ksp-core-lib` : ```text Pubkey Error / ErrorCode / Result Program IDs fondamentaux ``` `Pubkey` est réexporté depuis le crate-root Interface afin qu'un consumer wire n'introduise aucun wrapper d'identité parallèle. Les Program IDs restent possédés et répertoriés par Core. La dependency direction candidate `0.2.13` reste strictement : ```text ksp-interface-lib └── ksp-core-lib └── solana-pubkey ``` ## Surface publique `0.2.13` La façade crate-root expose exactement : ```text Pubkey ProgramAccountMeta MAX_PROGRAM_INSTRUCTION_ACCOUNTS ProgramInstruction MAX_PROGRAM_INSTRUCTION_DATA_LEN ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED ``` Aucun module interne n'est public. ### `ProgramAccountMeta` `ProgramAccountMeta` représente un compte ordonné d'une instruction avec : ```text pubkey is_signer is_writable ``` Les champs restent privés. Les constructeurs publics sont `readonly(pubkey, is_signer)` et `writable(pubkey, is_signer)`, complétés par les accessors `pubkey()`, `is_signer()` et `is_writable()`. La structure n'applique aucune sémantique spécifique à un programme et n'exige pas que la `Pubkey` appartienne au registry des Program IDs Core. ### `ProgramInstruction` `ProgramInstruction` représente un contrat passif borné : ```text program_id accounts: Vec data: Vec ``` `ProgramInstruction::try_new` consomme directement les deux `Vec`, conserve l'ordre et les doublons des accounts et préserve les octets opaques de `data` sans décodage. Les cas vides sont valides et une `program_id` inconnue du registry KSP reste admissible. ## Bornes d'admission Interface applique deux limites locales : | Limite | Valeur | |------------------------------------|----------| | `MAX_PROGRAM_INSTRUCTION_ACCOUNTS` | `255` | | `MAX_PROGRAM_INSTRUCTION_DATA_LEN` | `10_240` | Ces valeurs sont des **bornes d'admission Interface**. Elles ne constituent pas une garantie qu'une instruction donnée tient dans toutes les contraintes d'une transaction Solana top-level. La limite CPI de comptes uniques n'est notamment pas transformée en règle artificielle sur la liste d'account metas. Un dépassement utilise le code commun : ```text interface.program_instruction_limit_exceeded ``` Le contexte d'erreur est limité aux métadonnées sûres `field`, `actual_len` et `maximum_len`. Aucun payload arbitraire ni account meta hostile n'est recopié dans l'erreur. Le `Debug` de `ProgramInstruction` est volontairement borné : il affiche `program_id`, `account_count` et `data_len`, jamais les accounts complets ni les octets du payload. ## Codecs et runtime La foundation `0.2.13` n'ajoute aucun codec par réflexe : ```text serde / serde_json absents borsh absent wincode absent bincode absent solana-instruction absent ``` Des codecs/layouts/discriminants spécifiques pourront être ajoutés ultérieurement uniquement lorsqu'un vertical Program réel en démontre le besoin et que leur ownership wire appartient bien à Interface. La crate ne produit aucun événement runtime. Elle ne dépend donc pas de `ksp-logging-lib` et ne possède ni `constants.rs` ni `TRACING_TARGET`. Si un futur comportement Interface exige réellement du logging, le runtime devra passer par la façade Logging KSP plutôt que par une dépendance directe à Tracing. ## Frontières `ksp-interface-lib` ne possède pas : ```text RPC / WebSocket / gRPC provider DTOs Transport wallet / signature Config / environnement persistence / Store Program decoding / recognition / proofs execution policy / signers transaction replay / CPI path / runtime logs lifecycle réseau ``` La foundation Program API est reportée à `0.2.14`. Les wires génériques d'acquisition/CORE restent reportés à `0.3.2+`. ## Références - [Usage public](USAGE.md) - [Plan `0.2.13`](../../docs/plans/020-V0_2_13_INTERFACE_PLAN.md) - [Validation `0.2.13`](../../docs/validation/016-V0_2_13_INTERFACE.md) - [Architecture Wire + Program](../../docs/architecture/006-WIRE_AND_PROGRAM.md)