124 lines
8.7 KiB
Markdown
124 lines
8.7 KiB
Markdown
<!-- file: README.md -->
|
||
<!-- version: 13 -->
|
||
|
||
# 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-onchain-transport`: 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`.
|
||
|
||
`0.1.0-pre.014` confirme la parité de l’API publique `ExApi*` avec bot2 et remplace les 104 frontières temporaires d’exécution par des squelettes `Ex*Executor`. Chaque squelette référence uniquement ses Program IDs enregistrés, annonce `Maybe` sur sa surface et construit exclusivement un plan réservé à zéro instruction. Les exécuteurs opérationnels seront portés séparément, en commençant par Solana Core puis SPL.
|
||
|
||
`0.1.0-pre.015` rend `ExSolanaCoreExecutor` fonctionnel. Il construit des plans déterministes pour 109 opérations natives réparties sur 18 surfaces, conserve les refus explicites des programmes historiques non exécutables et expose ses intents sous les préfixes bot3 `ExSolanaCore*` et `EX_SOLANA_CORE_*`. Les 103 autres exécuteurs restent réservés jusqu’à leur port fonctionnel.
|
||
|
||
`0.1.0-pre.016` intègre le moteur transversal `ExSafetyChecker` et rend `ExSplMemoExecutor` fonctionnel. Memo v4 produit une instruction officielle bornée et soumise à simulation ; les générations historiques v1/v3 restent decode-only. Les 102 autres exécuteurs restent réservés jusqu’à leur port fonctionnel.
|
||
|
||
|
||
### Migration pipeline
|
||
|
||
La tranche `0.1.0-pre.029` migre la planification et l’extraction core de `kb-pipeline`.
|
||
|
||
### Pipeline migré
|
||
|
||
`kb-pipeline` contient désormais l’extraction core et le replay contextuel de décodage avec matérialisation optionnelle.
|
||
|
||
|
||
### Backfill HTTP
|
||
|
||
La tranche `0.1.0-pre.031` ajoute l’orchestration HTTP de backfill : signatures explicites ou historiques par adresse, pagination bornée, hydration via `getTransaction`, retries, annulation, reprise déterministe et persistance des observations.
|
||
|
||
La migration de `kb-pipeline` couvre désormais le backfill, l'extraction core, le replay de décodage, la validation Token-2022 et les lectures stateful/préflight Token-2022 et ElGamal Registry.
|
||
|
||
|
||
### Migration `0.1.0-pre.037`
|
||
|
||
`kb-pipeline` inclut désormais les contrôles stateful bornés des opérations Solana natives.
|
||
|
||
## Recherche ciblée des exports TS-RS
|
||
|
||
Pour éviter `node_modules`, limiter la recherche aux sources Rust :
|
||
|
||
```bash
|
||
find kb-config kb-lib kb-app-demo-desktop -type f -name '*.rs' -print0 \
|
||
| xargs -0 grep -n 'export_to'
|
||
```
|
||
|
||
Le fichier `.env` optionnel est chargé depuis la racine du workspace, puis depuis `kb-app-demo-desktop/.env`. Les valeurs existantes de l'environnement ne sont pas remplacées.
|