Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.5-pre.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-31 09:45:27 +02:00
parent c7cfb9557d
commit c24e4c48f8
4 changed files with 1027 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md Normal file
View File

@@ -0,0 +1,234 @@
<!-- file: docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md -->
<!-- version: 1 -->
# Validation `0.3.5` — Interface passive acquisition events
## 1. Portée
Ce document est ouvert par `0.3.5-pre.001`. Il enregistre uniquement des constats d'audit et des décisions de gate réellement effectués ; aucun test Cargo de `0.3.5` n'est déclaré PASS dans cette tranche tant qu'il n'a pas été rejoué par l'opérateur.
Base :
```text
v0.3.4
workspace.package.version = 0.3.4
```
Version de travail :
```text
0.3.5-pre.1
```
## 2. Gate d'entrée `v0.3.4`
Le log opérateur fourni avec l'archive indique un gate stable `v0.3.4` propre : audits Rust/Markdown, `cargo check`, Clippy, tests ciblés des crates, `cargo test --workspace`, `ksp-store-lib --no-default-features` et graphes Store ont été exécutés sans échec visible ; les smokes réseau restent explicitement ignorés/opt-in.
Cette preuve est l'entrée de `0.3.5`. Elle n'est pas réétiquetée comme validation exécutée dans l'environnement d'assemblage de `pre.001`.
## 3. Gate de lecture `pre.001`
| Contrôle | Résultat | Preuve / décision |
|---------------------------------------|----------|--------------------------------------------------------------------------------------------------------|
| règles globales relues | PASS | familles KSP-API/TRANSPORT/STORE/NOTIFY/PROC/REL et DEP applicables relues |
| architecture durable relue | PASS | Interface passif, Transport protocol/runtime, Store persistant, composition owner des conversions |
| fondation Interface stable relue | PASS | surface Program petite ; dépendance normale Core-only |
| Store API RAW relu | PASS | `RawTransaction*` + `RawAccount*` restent Store-owned |
| Store/PostgreSQL `0.3.2`–`0.3.4` relu | PASS | RAW physique 10/10 fermé ; aucune rétention account |
| surfaces HTTP/WS/gRPC/Helius relues | PASS | status/log/slot/vote/account/transaction/block/Entry inventoriés |
| documentation Solana courante auditée | PASS | `slotSubscribe`, `slotsUpdatesSubscribe`, status/log/vote/account/program, getTransaction/getBlock |
| Yellowstone upstream courant audité | PASS | `SlotStatus` et familles SubscribeUpdate courantes |
| Helius courant audité | PASS | standard WSS préserve wire Solana ; Enhanced `transactionSubscribe` reste extension provider |
| producer/consumer inventory | PASS | une intersection lifecycle slot justifiée ; autres familles non admises |
| threat model | PASS | mega enum, Option soup, Store duplication, timestamp/finality confusion et provider promotion couverts |
| sizing release | PASS | 7 prereleases prévues avant `rel.001`, une seule famille fonctionnelle |
## 4. Matrice de décision par famille
| Famille | Décision | Owner | Motif déterminant |
|---------------------------------------|-----------------|-----------------|---------------------------------------------------------------------------------------------|
| slot lifecycle intersection | ADMIS | Interface | faits compacts exacts produits par Solana WS et Yellowstone ; pas de persistence |
| root/finality | REPORTÉ | Transport | aucune équivalence normative exacte `root` <-> `Finalized` retenue |
| optimistic/confirmed | REPORTÉ | Transport | aucune équivalence normative exacte retenue |
| logs realtime | REPORTÉ | Transport | pas de seconde surface indépendante équivalente ; Yellowstone logs restent transaction/meta |
| transaction status | REPORTÉ | Transport | HTTP snapshot != WS one-shot commitment != Yellowstone execution update |
| vote | REPORTÉ | Transport | gossip pré-consensus != transaction qualifiée `is_vote` |
| account/program | REJET Interface | Store/Transport | risque de doublon `RawAccountState`/observation ou wrapper Transport |
| transaction | REJET Interface | Store/Transport | `RawTransaction`/observation déjà persistants |
| block | REJET Interface | Transport | conteneur/payload d'acquisition ; aucun besoin passif transversal démontré |
| Yellowstone Entry | REJET Interface | Transport | surface protocolaire mono-producer |
| persisted-data available notification | REJET Interface | Store API | ownership normatif `KSP-NOTIFY-001..006` |
| Helius Enhanced transaction | REJET Interface | Transport | extension provider-specific |
## 5. Intersection lifecycle retenue
| Stage Interface prévu | Producer Solana standard | Producer Yellowstone | Verdict | Détails exclus du contrat commun |
|--------------------------|----------------------------------------|----------------------|---------|-------------------------------------------------------------------------|
| `Processed` | `slotSubscribe` | `Processed` | PASS | WS parent/root ; Yellowstone filters/created_at/parent |
| `FirstShredReceived` | `slotsUpdates::FirstShredReceived` | `FirstShredReceived` | PASS | timestamps/metadata source |
| `Completed` | `slotsUpdates::Completed` | `Completed` | PASS | timestamps/metadata source |
| `CreatedBank` | `slotsUpdates::CreatedBank` | `CreatedBank` | PASS | parent reste dans le DTO Transport riche |
| `Dead` | `slotsUpdates::Dead` | `Dead` | PASS | diagnostic `err`/`dead_error` et timestamp restent Transport |
| `Frozen` | `slotsUpdates::Frozen` | — | FAIL | pas d'intersection |
| `OptimisticConfirmation` | `slotsUpdates::OptimisticConfirmation` | `Confirmed` | FAIL | noms/semantiques proches insuffisants sans équivalence normative exacte |
| `Root` | `rootSubscribe` / `slotsUpdates::Root` | `Finalized` | FAIL | aucune normalisation root/finalized inventée |
| `Confirmed` | — | `Confirmed` | FAIL | producer standard exact absent |
| `Finalized` | — | `Finalized` | FAIL | producer standard exact absent |
## 6. Validation anti-Option-soup
Les modèles suivants sont explicitement **non admis** par le gate :
```text
TransactionStatusObservation {
confirmations?: ...,
confirmation_status?: ...,
received?: ...,
is_vote?: ...,
transaction_index?: ...,
...
}
SlotLifecycleEvent {
parent?: ...,
root?: ...,
timestamp?: ...,
dead_error?: ...,
provider?: ...,
...
}
```
La surface visée reste conceptuellement :
```text
SlotLifecycleEvent { slot, stage }
```
## 7. Validation anti-duplication Store
| Modèle Store stable | Action `0.3.5` | Justification |
|---------------------------------|---------------------|------------------------------------------------|
| `RawTransaction` | inchangé | payload durable/replayable |
| `RawTransactionObservation` | inchangé | provenance persistante |
| `RawAccountState` | inchangé | état account durable |
| `RawAccountObservation` | inchangé | observation persistante |
| pagination/cursors RAW | inchangés | contrats de navigation Store |
| retention/tombstone transaction | inchangés | lifecycle de persistence Store |
| notification after commit | non implémentée ici | ownership Store API réservé par `KSP-NOTIFY-*` |
Canari conceptuel : aucun futur fichier source Interface de `0.3.5` ne doit importer `ksp_store_api`, `ksp_store_lib` ou copier leurs modèles.
## 8. Validation dependency/ownership
État de l'archive stable inspecté :
```text
crates/ksp-interface-lib/Cargo.toml
runtime dependency = ksp-core-lib seulement
```
Cible `0.3.5` :
```text
ksp-interface-lib -> ksp-core-lib
ksp-interface-lib -X-> ksp-onchain-transport-lib
ksp-interface-lib -X-> ksp-store-api
ksp-interface-lib -X-> ksp-store-lib
ksp-interface-lib -X-> ksp-program-api
ksp-interface-lib -X-> serde/tracing/tokio/channel runtime additions
```
Le `cargo tree` ne peut pas être exécuté dans l'environnement d'assemblage actuel, où `cargo` est absent. Le gate opérateur est donc obligatoire sur l'overlay.
## 9. Consumer concret retenu
Consumer proche documenté par l'architecture : futur worker RAW live / composition d'acquisition.
Usage possible sans dépendance protocol-specific :
```text
Solana standard WS -----------+
+-> converter composition -> SlotLifecycleEvent -> réaction lifecycle du consumer
Yellowstone gRPC -------------+
```
`0.3.6` backfill n'est pas forcé d'utiliser ce type ; il reste une composition historique Transport + Store.
## 10. Threat gates
| Gate | Attendu `0.3.5` | Statut `pre.001` |
|----------------------------------|-----------------------------------------------|------------------|
| mega enum | absent | PLAN PASS |
| protocol/provider enum leakage | absent | PLAN PASS |
| timestamp semantics conflated | absent | PLAN PASS |
| root/finalized conflated | absent | PLAN PASS |
| optimistic/confirmed conflated | absent | PLAN PASS |
| dead diagnostic in shared API | absent | PLAN PASS |
| RAW Store duplication | absent | PLAN PASS |
| event persistence | absent | PLAN PASS |
| event bus/runtime | absent | PLAN PASS |
| network id duplicated from Store | absent | PLAN PASS |
| cross-network use | composition doit conserver son scope réseau | À CANARIER |
| public enum evolution | `SlotLifecycleStage` doit être non-exhaustive | À IMPLÉMENTER |
| Core-only graph | aucune dependency nouvelle | À REJOUER |
| external consumer | type consommable depuis crate externe | À IMPLÉMENTER |
## 11. Fichiers de `pre.001`
Ajoutés :
```text
docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md
docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md
deltas/0.3.5/pre.001.md
```
Modifié :
```text
Cargo.toml
```
Aucun autre fichier ne doit changer dans cet overlay.
## 12. Validations exécutées dans l'environnement d'assemblage
Exécutables sans Cargo :
```text
python3 scripts/audit_rust_workspace_rules.py
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.5
```
Le résultat réel est enregistré dans `deltas/0.3.5/pre.001.md` après exécution.
## 13. Validations opérateur requises
À appliquer sur le repository `v0.3.4` après extraction de l'overlay :
```text
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.5
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-interface-lib
```
Aucun `cargo test -p ksp-program-api` n'est requis par le contenu de `pre.001`, car aucun contrat public Interface n'est encore modifié. Il devient requis à partir de la première tranche qui change réellement la surface publique concernée.
## 14. Exit gate `pre.001`
`pre.001` est prêt à livrer lorsque :
```text
plan + validation + delta existent
workspace.package.version = 0.3.5-pre.1
une seule famille est admise : SlotLifecycle
stages admis = Processed / FirstShredReceived / Completed / CreatedBank / Dead
logs/status/vote/root/account/transaction/block/Entry/post-commit sont classés explicitement
aucun fichier Rust/Transport/Store n'est modifié
les audits statiques disponibles sont propres
les gates Cargo non exécutables sont explicitement laissés à l'opérateur
```