<!-- file: README.md -->
<!-- version: 21 -->

# Khadhroony Bot3

`khadhroony-bot3` est un workspace Rust 2024 dédié à l’acquisition, au décodage, à la matérialisation et à l’exécution contrôlée de transactions Solana.

## Architecture

Le workspace contient onze crates :

- `ks-core` : erreurs et primitives transversales ;
- `ks-config` : chargement et validation de la configuration ;
- `ks-lib` : modèles, décodeurs, exécuteurs et matérialisateurs ;
- `ks-logging` : logging et tracing ;
- `ks-program-ids` : registre canonique des programmes et comptes Solana ;
- `ks-pipeline` : pipeline généraliste de backfill, extraction, replay et orchestration ;
- `ks-pipeline-demo-scenarios` : scénarios synthétiques et campagnes Devnet/Testnet automatisables ;
- `ks-onchain-transport` : transports RPC HTTP et WebSocket ;
- `ks-store` : contrats de stockage et adaptateur PostgreSQL ;
- `ks-wallet` : frontière de wallet et signataires ;
- `kb-app-demo-desktop` : application Tauri de démonstration et validation opérateur.

La série `0.5.x` prépare la séparation explicite entre le domaine applicatif `khadhroony-bot` et les bibliothèques généralistes `khadhroony-solana`. En `0.5.1`, les dix crates généralistes doivent migrer vers les noms `ks-*` / `ks_*`, tandis que `kb-app-demo-desktop` conserve son nom et reste une application du workspace Bot. Le workspace, le dépôt et le répertoire racine restent nommés `khadhroony-bot3` pendant cette migration et ne doivent pas être renommés avant `1.0` ou une version ultérieure explicitement dédiée. La politique de migration est définie dans [`docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md).

Références :

- [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) ;
- [`docs/architecture/CRATE_MAP.md`](docs/architecture/CRATE_MAP.md) ;
- [`docs/architecture/PIPELINE_ARCHITECTURE.md`](docs/architecture/PIPELINE_ARCHITECTURE.md) ;
- [`docs/architecture/STORAGE_ARCHITECTURE.md`](docs/architecture/STORAGE_ARCHITECTURE.md) ;
- [`docs/architecture/SURFACE_CRATE_MATRIX.md`](docs/architecture/SURFACE_CRATE_MATRIX.md).

## Capacités principales

- acquisition HTTP et WebSocket ;
- stockage PostgreSQL canonique ;
- extraction Solana Core et replay contextualisé ;
- décodeurs, matérialisateurs et exécuteurs Solana Core et SPL ;
- exécution simulation-first avec contrôle des signers, coûts, confirmations et postconditions ;
- scénarios synthétiques, campagnes réseau réutilisables et panneaux desktop ;
- couverture Metaplex Token Metadata bornée, avec parcours Devnet représentatifs réellement exécutés.

Le statut précis d’une version appartient au [`CHANGELOG.md`](CHANGELOG.md), au [`ROADMAP.md`](ROADMAP.md) et aux rapports de validation, pas au présent README généraliste.

## Documentation

- [`RULES.md`](RULES.md) : index des règles ;
- [`ROADMAP.md`](ROADMAP.md) : trajectoire fonctionnelle ;
- [`CHANGELOG.md`](CHANGELOG.md) : versions fonctionnelles clôturées ;
- [`docs/README.md`](docs/README.md) : index documentaire ;
- [`prompts/001.README.md`](prompts/001.README.md) : prompts actifs.

## Validation générale

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --all-targets
python3 scripts/audit_rust_workspace_rules.py
cargo test --workspace
```

Lorsque le desktop est concerné en développement :

```bash
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
```

Pour un build desktop de release :

```bash
cargo tauri build -c kb-app-demo-desktop/tauri.conf.json
```

Les scripts `npm run dev` et `npm run build` ne sont pas lancés directement : Tauri les pilote via sa configuration.