4.5 KiB
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 :
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 :
ksp-interface-lib
└── ksp-core-lib
└── solana-pubkey
Surface publique 0.2.13
La façade crate-root expose exactement :
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 :
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é :
program_id
accounts: Vec<ProgramAccountMeta>
data: Vec<u8>
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 :
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 :
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 :
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+.