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

v0.3.7-pre.016

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-03 06:26:49 +02:00
parent a266a4d7b6
commit d8f7c9bd8b
15 changed files with 423 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/000-README.md
View File

File diff suppressed because one or more lines are too long

4
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
<!-- version: 9 -->
<!-- version: 10 -->
# Couches et dépendances KSP
@@ -134,7 +134,7 @@ Les applications Tauri restent minces :
- instrumentation frontend ;
- aucun déplacement de logique de transport, Wallet, Config, Program, Store ou Materializer dans Tauri.
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, backfill/RAW tooling, CORE tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites.
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, `ksp-app-backfill-desk`, Store/RAW tooling, CORE tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites. `ksp-app-backfill-desk` compose Config, Transport HTTP, Store et `ksp-job-backfill-lib` sans absorber découverte, retry/rate-limit, persistance ou checkpoint ; son frontend ne reçoit que des DTOs sûrs et le checkpoint de reprise reste Rust-only.
## Workers et jobs

9
docs/architecture/003-COMPONENT_CONTRACTS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# Contrats initiaux des composants KSP
@@ -203,14 +203,17 @@ KSP privilégie des applications spécialisées servant à valider/exploiter une
```text
ksp-app-config-desk
ksp-app-wallet-desk
price desk
backfill/raw tooling
ksp-app-solprices-desk
ksp-app-backfill-desk
ksp-app-store-desk
CORE tooling
ksp-app-market-desk
```
Une application globale reste future.
`ksp-app-backfill-desk` est l'interface spécialisée du premier job historique. Elle dépend des façades KSP nécessaires à la composition (`ksp-config-lib`, `ksp-job-api`, `ksp-job-backfill-lib`, `ksp-onchain-transport-lib`, `ksp-store-lib`, Core et Logging), garde Store/Transport/checkpoint côté Rust et expose uniquement les options, demandes opérateur bornées, états latest-value et acquittements de contrôle sûrs.
## Progression verticale Program
À partir de DECODE :

4
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 31 -->
<!-- version: 32 -->
# Inventaire initial des composants KSP
@@ -42,7 +42,7 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4` | backend référence : fondation, RawTransaction et RawAccountState |
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6` | backfill `RawTransaction` borné via Transport observé + Store, checkpoint et runtime |
| Backfill Desk | nom à fixer | app | Retenu | `0.3.7` | contrôle/inspection du backfill RAW |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7` | Start/monitoring/Cancel/Resume in-session du backfill RAW via façades KSP |
| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus |
| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW |
| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE |

15
docs/architecture/005-DEPENDENCY_GRAPH.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 20 -->
<!-- version: 21 -->
# Graphe de dépendances KSP
@@ -425,16 +425,21 @@ ksp-app-solprices-desk
L'application est une HID pure. Elle ne dépend d'aucun SDK provider, ne construit aucune requête HTTP provider et ne connaît ni endpoint, ni credential, ni limite provider. Les rows et actions de refresh sont alimentées par les descriptors/états/opérations génériques de `ksp-offchain-transport-lib`.
### Backfill app
### Backfill Desk
```text
backfill app
-> ksp-job-api
-> concrete backfill job
ksp-app-backfill-desk
-> ksp-core-lib
-> ksp-config-lib
-> ksp-job-api
-> ksp-job-backfill-lib
-> ksp-logging-lib
-> ksp-onchain-transport-lib
-> ksp-store-lib
```
La Desk compose les ressources et contrôles du job sans traverser la façade Store : aucune dépendance directe à `ksp-store-api`, `ksp-store-postgres-lib`, `tokio-postgres`, `reqwest`, `tonic` ou `yellowstone-grpc-proto`. Le frontend ne connaît que des rôles HTTP logiques et des DTOs sûrs ; endpoints, credentials, backend Store, RAW et checkpoint concret restent sous les composants Rust propriétaires.
### Market Desk
```text

4
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 10 -->
<!-- version: 11 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -90,6 +90,8 @@ Le job :
- publie des snapshots latest-value sûrs sans payload RAW ni secrets/URLs Transport ;
- n'effectue aucun décodage Program et n'écrit aucun fait CORE/DECODE/SPECIALIZED.
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
### Worker RAW live
Le worker live futur :

14
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
<!-- version: 8 -->
<!-- version: 9 -->
# Applications, services, scenarios et control plane
@@ -77,6 +77,7 @@ Exemples de familles spécialisées :
ksp-app-config-desk
ksp-app-wallet-desk
ksp-app-solprices-desk
ksp-app-backfill-desk
ksp-app-store-desk
ksp-app-worker-<role>-desk
ksp-app-scenario-<domain>-<environment>-desk-demo
@@ -106,12 +107,23 @@ ksp-app-solprices-desk
-> ksp-config-lib
-> ksp-offchain-transport-lib
ksp-app-backfill-desk
-> ksp-core-lib
-> ksp-config-lib
-> ksp-job-api
-> ksp-job-backfill-lib
-> ksp-logging-lib
-> ksp-onchain-transport-lib
-> ksp-store-lib
ksp-app-store-desk
-> ksp-store-lib
```
`ksp-store-lib` réexporte la surface Store commune nécessaire aux applications ; une app ne dépend pas directement de `ksp-store-api` uniquement pour atteindre les modèles/capabilities, et ne dépend jamais d'une crate backend concrète.
Backfill Desk suit exactement cette règle : elle ouvre Store via `ksp-store-lib`, construit le pool HTTP via `ksp-onchain-transport-lib`, puis remet ces ressources à `ksp-job-backfill-lib`. Start/Cancel/Resume restent des opérations applicatives de composition ; le checkpoint de reprise et les ressources physiques ne deviennent jamais des DTOs Tauri.
Les couches N1–N4 expriment des responsabilités et une direction de dépendances ; elles n'imposent pas de traverser toutes les couches intermédiaires.
## Tauri

36
docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md -->
<!-- version: 15 -->
<!-- version: 16 -->
# Plan v0.3.7 — Backfill Desk
@@ -108,27 +108,31 @@ main
Les DTOs sont possédés par l'application et dérivés TS-RS uniquement à cette frontière.
| Élément | Direction | Contenu | Validation / source de vérité | Sensibilité |
|-----------------------------|------------|-----------------------------------------------------------------------------------------------|------------------------------------------|--------------|
| `BackfillDeskOptionsDto` | Rust -> UI | réseau, rôles compatibles, commitments, scopes, bornes, readiness | Config + Transport + constantes Backfill | sûre |
| `BackfillStartRequestDto` | UI -> Rust | scope inputs, commitment, rôle, bornes, optional min context slot | conversion stricte vers types KSP | métier borné |
| `BackfillRunStatusDto` | Rust -> UI | job state, phase, compteurs, boundary, checkpoint_present, contiguous_completed, failure code | `JobNotification<BackfillJobSnapshot>` | sûre |
| `BackfillCancelResponseDto` | Rust -> UI | accepted + état courant | `BackfillJobHandle` | sûre |
| `BackfillResumeResponseDto` | Rust -> UI | accepted/new job status | checkpoint Rust détenu par AppState | sûre |
| `SafeAppErrorDto` | Rust -> UI | domain/code + message app maîtrisé | mapping applicatif | sûre |
| Élément | Direction | Contenu | Validation / source de vérité | Sensibilité |
|----------------------------------|------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------|--------------|
| `BackfillDeskOptionsDto` | Rust -> UI | réseau, rôles, commitments, scopes, bornes, readiness, Program IDs autocomplete | Config + Transport + Core + Backfill | sûre |
| `BackfillRequestLimitsDto` | Rust -> UI | defaults + maxima de campagne | constantes publiques Backfill | sûre |
| `BackfillStartRequestDto` | UI -> Rust | scope inputs, commitment, rôle, bornes, optional min context slot | conversion stricte vers types KSP | métier borné |
| `BackfillRequestPreviewDto` | Rust -> UI | request validée sans valeur d'adresse/signature | mapping applicatif + `BackfillRequest` | sûre |
| `BackfillStartResponseDto` | Rust -> UI | JobId backend + état initial | slot single-run | sûre |
| `BackfillRunStatusDto` | Rust -> UI | job state, phase, compteurs, boundary, checkpoint_present, contiguous_completed, failure code | `BackfillSnapshotSource` | sûre |
| `BackfillCancelResponseDto` | Rust -> UI | accepted + JobId ciblé + état | `BackfillJobHandle` | sûre |
| `BackfillResumeResponseDto` | Rust -> UI | accepted + nouveau JobId + état | checkpoint Rust détenu par `BackfillRunState` | sûre |
| `ProgramIdAutocompleteOptionDto` | Rust -> UI | program_id + metadata publiques de taxonomie | `ksp_core_lib::entries()` | publique |
| `CommandErrorDto` | Rust -> UI | domain/code + message app maîtrisé | mapping applicatif | sûre |
Commandes prévues :
Commandes finales :
```text
backfill_options() -> BackfillDeskOptionsDto
backfill_status() -> BackfillRunStatusDto
backfill_start(request) -> BackfillRunStatusDto
backfill_status() -> Option<BackfillRunStatusDto>
backfill_validate_request(request) -> BackfillRequestPreviewDto
backfill_start(request) -> BackfillStartResponseDto
backfill_cancel(job_id) -> BackfillCancelResponseDto
backfill_resume() -> BackfillResumeResponseDto
backfill_reset() -> BackfillRunStatusDto
```
Le monitoring continu ne dépend pas du parsing de logs. Le backend possède un bridge latest-value qui attend `JobSnapshotSource::wait_for_change`, projette le snapshot et émet un événement Tauri borné, par exemple `backfill-status-changed`. `backfill_status` reste le chemin de resynchronisation initiale/explicite.
Le monitoring continu ne dépend pas du parsing de logs. Le backend possède un bridge latest-value depuis `BackfillSnapshotSource`, projette le snapshot et émet l'événement Tauri stable `ksp-backfill-status`. `backfill_status` reste le chemin de resynchronisation initiale/explicite.
Aucun `BackfillCheckpoint`, `Store`, `HttpTransportPool`, sender/receiver Tokio ni payload RAW n'est sérialisé vers le frontend.
@@ -314,7 +318,9 @@ La tranche `pre.015` n'ajoute aucune capacité ni aucun test. Elle matérialise
### pre.016 — réconciliation documentaire
README/USAGE/plan/validation et architecture seulement si la surface finale l'exige. Aucun nouveau runtime.
Le gate technique final `pre.015` est intégralement vert : `cargo fmt --check`, audits, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, `cargo test --workspace --all-targets --all-features`, arbres Cargo ciblés, `cargo tree --duplicates` et build Tauri Linux passent. Le run workspace agrège 1 494 tests passés, 0 échec et 15 tests ignorés explicitement opt-in/operator-only ; le build produit les bundles `.deb`, `.rpm` et `.AppImage`.
La tranche réconcilie exclusivement les documents durables : README/USAGE de Backfill Desk, index documentaires, plan/validation et architecture courante. Aucun runtime, test, frontend ou Config n'est rouvert.
### pre.017 — préparation publication

3
docs/validation/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/000-README.md -->
<!-- version: 35 -->
<!-- version: 36 -->
# Validations KSP
@@ -32,3 +32,4 @@ Documents :
- [`021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — matrice finale de `0.3.4 — RawAccountState + complétude RAW` : quatre capabilities account supplémentaires, V002, pagination/idempotence et conformance Store 10/10.
- [`022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md`](022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md) — matrice finale de `0.3.5 — Interface acquisition events` : événements passifs slot/transaction, façade crate-root, bornes/debug et firewall Interface.
- [`023-V0_3_6_JOB_API_BACKFILL.md`](023-V0_3_6_JOB_API_BACKFILL.md) — matrice candidate de `0.3.6 — Job API + RAW transaction backfill` : lifecycle/notifications runtime-neutral, scopes, provenance, RAW v1, Store/idempotence, concurrence/checkpoint, annulation/snapshots, hardening externe et gate workspace final.
- [`024-V0_3_7_BACKFILL_DESK.md`](024-V0_3_7_BACKFILL_DESK.md) — matrice candidate de `0.3.7 — Backfill Desk` : composition Config/Transport/Store/Job, scopes et rôles HTTP, single-run, monitoring latest-value, Cancel, Resume in-session Rust-only, autocomplete Program IDs, hardening et gate workspace/Tauri final.

50
docs/validation/024-V0_3_7_BACKFILL_DESK.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/024-V0_3_7_BACKFILL_DESK.md -->
<!-- version: 25 -->
<!-- version: 26 -->
# Validation v0.3.7 — Backfill Desk
@@ -99,15 +99,15 @@ Le journal opérateur fourni rapporte `cargo clean`, `cargo fmt`, audits Rust/Ma
- [X] Transport readiness et role inventory sûrs.
- [X] Store readiness et cohérence réseau.
- [X] Quatre scopes + commitments + bornes mappés.
- [ ] Single active run + Start.
- [ ] Snapshot latest-value bridge.
- [ ] Cancel + races terminales.
- [ ] Checkpoint/frontier projection + Resume in-session.
- [ ] Frontend/security/composition tests verts.
- [ ] `cargo test --workspace` final vert.
- [ ] `(cd crates/ksp-app-backfill-desk && cargo tauri build)` final vert.
- [ ] Smoke live opt-in exécuté si environnement sûr disponible, sinon explicitement non requis.
- [ ] Réconciliation README/USAGE/plan/validation dans sa tranche dédiée.
- [X] Single active run + Start.
- [X] Snapshot latest-value bridge.
- [X] Cancel + races terminales.
- [X] Checkpoint/frontier projection + Resume in-session.
- [X] Frontend/security/composition tests verts.
- [X] `cargo test --workspace --all-targets --all-features` final vert.
- [X] `(cd crates/ksp-app-backfill-desk && cargo tauri build)` final vert.
- [X] Smokes Mainnet opérateur antérieurs suffisants ; aucun nouveau smoke final requis.
- [X] Réconciliation README/USAGE/plan/validation/architecture dans `pre.016`.
- [ ] Prompt 0.3.8 + CHANGELOG + ROADMAP uniquement dans la lane de publication.
## 9. pre.002 — scaffold desktop
@@ -651,4 +651,34 @@ Un `cargo clean` préalable est optionnel : il peut être utilisé pour une reco
- [X] gate final borné au workspace, arbres Cargo et build Tauri ;
- [ ] gate opérateur final à exécuter ;
- [ ] `pre.016` interdit tant que ce gate n'est pas intégralement vert.
## 32. `pre.015` — gate technique final
Le gate opérateur final est intégralement vert sur `0.3.7-pre.15` :
- [X] `cargo fmt --all -- --check` ;
- [X] audits Rust/exports/workspace et Markdown ;
- [X] `cargo check --workspace` ;
- [X] `cargo clippy --workspace --all-targets --all-features -- -D warnings` sans warning ;
- [X] `cargo test --workspace --all-targets --all-features` : 1 494 tests passés, 0 échec, 15 tests ignorés explicitement opt-in/operator-only ;
- [X] arbres normal/features de `ksp-app-backfill-desk` et `ksp-job-backfill-lib` produits ;
- [X] `cargo tree --duplicates` exécuté et revu ;
- [X] `cargo tauri build` final réussi ;
- [X] bundles Linux `.deb`, `.rpm` et `.AppImage` produits ;
- [X] aucun smoke live supplémentaire requis, les smokes Mainnet précédents ayant déjà prouvé Start, monitoring, Cancel et Resume réels.
Aucun défaut technique n'est reporté vers la réconciliation documentaire.
## 33. `pre.016` — réconciliation documentaire finale
La surface candidate est réconciliée sans rouvrir le runtime :
- [X] `crates/ksp-app-backfill-desk/README.md` décrit responsabilités, composition, frontières et build de manière durable ;
- [X] `crates/ksp-app-backfill-desk/USAGE.md` décrit l'utilisation sans journal de prerelease ni preuve de gate ;
- [X] le plan est réaligné sur les commandes réellement livrées et l'événement `ksp-backfill-status` ;
- [X] les index `docs/000-README.md` et `docs/validation/000-README.md` référencent `0.3.7` ;
- [X] l'inventaire d'architecture fixe `ksp-app-backfill-desk` comme composant implémenté ;
- [X] Layers/Contracts/Dependency Graph/Apps & Services décrivent la composition finale et les firewalls ;
- [X] README racine mentionne la surface desktop Backfill sans faire de la documentation durable un changelog ;
- [X] CHANGELOG et ROADMAP restent réservés à `pre.017` ;
- [X] aucun code, test, frontend, Config ou manifest de crate n'est modifié.