132 lines
4.5 KiB
Markdown
132 lines
4.5 KiB
Markdown
<!-- file: crates/ksp-interface-lib/README.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# 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<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 :
|
|
|
|
```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)
|