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

# Khadhroony Bot3

Khadhroony Bot3 is the consolidated successor workspace to `khadhroony-bot2`.

## Workspace crates

- `kb-core`: foundation errors and shared primitives.
- `kb-config`: configuration contracts.
- `kb-lib`: all decoder, executor and materializer APIs and implementations.
- `kb-logging`: logging and tracing runtime.
- `kb-program-ids`: Solana program identifier registry.
- `kb-pipeline`: ingestion, decoding, materialization and execution orchestration.
- `kb-rpc`: HTTP and WebSocket Solana transports.
- `kb-store`: store-neutral contracts and PostgreSQL implementation modules.
- `kb-wallet`: wallet and signer support.
- `kb-app-demo`: the only binary retained during the initial migration.

## Migration principle

The previous workspace is preserved under `migration/khadhroony-bot2-reference`. The new workspace compiles independently as a controlled scaffold. Public APIs are ported into `kb-lib` module by module, with compatibility recorded in `migration/module-map.json`.

## Validation

```bash
cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
```

## État de migration `0.1.0-pre.001`

- `kb-wallet` remplace définitivement le scaffold `kb_wallet`.
- `kb-core` conserve l’architecture de `kb_core` : implémentations dans `error.rs` et `module.rs`, façade et réexports dans `lib.rs`.
- Les prochaines APIs consolidées de `kb-lib` suivront la même règle : aucun contrat métier ne sera défini directement dans `lib.rs`.

## Contrats consolidés

À partir de `0.1.0-pre.002`, `kb-lib` porte les modèles et contrats fondamentaux autrefois répartis entre `kb_model`, `kb_decoder_api`, `kb_materializer_api` et `kb_execution_api`. Les implémentations restent dans des modules dédiés ; `kb-lib/src/lib.rs` ne contient que les déclarations de modules et les réexports publics.

## Stockage consolidé

À partir de `0.1.0-pre.003`, `kb-store` remplace le scaffold initial par une implémentation complète :

- contrats store-neutral : DTO, entités, pagination, santé et traits de repository ;
- adaptateur PostgreSQL : connexion, initialisation idempotente, requêtes, diagnostics et replay ;
- façade unique dans `kb-store/src/lib.rs` ;
- modèle de replay partagé conservé dans `kb-lib`, sans duplication ;
- options PostgreSQL indépendantes de `kb-config`, adaptées par la frontière applicative.

## Décodeurs consolidés

`0.1.0-pre.004` porte le décodeur Solana Core dans `kb-lib`. `0.1.0-pre.005` ajoute SPL Memo v1, v3 et v4. `0.1.0-pre.006` ajoute le décodeur SPL Token classique avec ses 28 tags publiés, son wire borné, ses formes d’autorité et son `Batch` structuré. `0.1.0-pre.007` ajoute le programme SPL Associated Token Account avec ses trois instructions, sa forme historique `Create` vide et la validation canonique des PDA pour SPL Token classique et Token‑2022.

`0.1.0-pre.008` porte le décodeur Token‑2022 maximal, son parseur d’états Mint/Account/Multisig et de TLV, ainsi que le programme indépendant du registre ElGamal. Les deux composants gardent des frontières et des targets de tracing distincts. Tous les décodeurs migrés utilisent les mêmes contrats contextualisés, la même façade publique et aucune dépendance inverse vers `kb-store`.

`0.1.0-pre.009` porte le décodeur indépendant Metaplex Token Metadata. Il couvre les 58 discriminateurs d’instructions publiés `0..=57`, les 15 variantes de comptes `Key 0..=14`, les PDA officiels et les layouts courants, expérimentaux et historiques. Les metadata externes Metaplex restent séparées des metadata incorporées de Token‑2022, de Metaplex Core et de Bubblegum.

`0.1.0-pre.012` restaure les 98 squelettes de décodeurs réservés sous forme de types `Dc*Decoder` implémentant `DcApiProtocolDecoder`. Les 97 surfaces identifiables déclarent leur Program ID exact dans `kb-program-ids`; Anchor reste volontairement sans identifiant statique. Ces squelettes répondent `Maybe` sans produire de faux événement et sont exposés uniquement par la façade `kb_lib`.

## Matérialisateurs consolidés

`0.1.0-pre.010` porte les quatre matérialisateurs Solana natifs dans `kb-lib` :

- `MtLifecycleMaterializer` pour les comptes System, nonces, ALT, loaders, Feature Gate, contextes ZK et rapports Slashing ;
- `MtAdminMaterializer` pour les assignations, configurations et autorités, avec ses projections stateful Token‑2022 et registre ElGamal ;
- `MtComplianceAuditMaterializer` pour les écritures et copies bornées de bytecode ;
- `MtStakingMaterializer` pour les transitions Stake et Vote commitées.

Les identités historiques des processors sont conservées pour la compatibilité des replays, tandis que les targets de tracing suivent désormais la hiérarchie `kb-lib.materializer.*`. Le contrat public `MtApiEventMaterializer`, ses modèles d’entrée et ses résultats restent réexportés à la racine de `kb-lib`, afin qu’un futur crate externe puisse fournir un matérialiseur sans dépendre d’une implémentation interne.

`0.1.0-pre.011` termine le port des matérialisateurs réellement implémentés dans bot2 :

- `MtTransactionAnnotationMaterializer` pour les Memo commitées ;
- `MtTokenAccountsMaterializer` pour les mutations SPL Token, le lifecycle ATA et les snapshots Token‑2022 ;
- `MtFeesMaterializer` pour les frais publics et confidentiels Token‑2022, sans prétendre déchiffrer les valeurs confidentielles ;
- `MtRiskMaterializer` pour les faits de risque SPL Token et ATA sans score arbitraire ;
- `MtMetadataMaterializer` pour les snapshots descriptifs Token‑2022 et Metaplex, sans fetch off-chain.

Les modules de matérialisation sont privés. Tous les contrats, types concrets et helpers destinés aux consommateurs externes sont exposés exclusivement par `kb-lib/src/lib.rs`. Des tests aval distincts protègent les contrats d’extension `DcApiProtocolDecoder`, `MtApiEventMaterializer` et `ExApiInstructionExecutor`.

`0.1.0-pre.013` remplace les 14 dernières frontières temporaires de matérialisation par des squelettes `Mt*Materializer`. Ils conservent le contrat historique `MtMaterializer`, implémentent également `MtApiEventMaterializer`, restent volontairement inactifs et ne produisent aucun faux événement via l’API bot3. Tous les types sont accessibles exclusivement depuis la façade `kb_lib`.