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

v0.1.0-pre.069

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-07-31 13:25:26 +02:00
parent f23ecd6675
commit 46071b7fed
21 changed files with 799 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
kb-store/README.md
View File

@@ -1,126 +1,52 @@
<!-- file: kb-store/README.md -->
<!-- version: 1 -->
<!-- version: 3 -->
# `kb-store`
# kb-store
`kb-store` regroupe les contrats de persistance neutres et l’adaptateur PostgreSQL de production de Khadhroony Bot3.
`kb-store` consolide les contrats de stockage et l’implémentation PostgreSQL de `khadhroony-bot3`.
La crate remplace l’ancienne séparation physique entre contrats et PostgreSQL, sans mélanger leurs responsabilités. Tous les modules restent privés et l’API stable est réexportée depuis `src/lib.rs`.
## Périmètre
## Architecture
La crate expose :
```text
src/
├── lib.rs
├── constants.rs
├── contracts.rs
├── contracts/
│ ├── dto.rs
│ ├── dto/
│ ├── entity.rs
│ ├── entity/
│ ├── error.rs
│ ├── health.rs
│ ├── pagination.rs
│ └── repository.rs
├── postgres.rs
└── postgres/
├── migrations.rs
├── query.rs
├── query/
├── replay_candidates.rs
├── repository.rs
├── repository/
├── store.rs
└── test_serial.rs
```
- DTO et entités raw, observations, Core, décodage, matérialisation et ledger ;
- traits async de repositories indépendants du backend ;
- pagination et filtres bornés ;
- `PostgresStore` et ses options de connexion ;
- initialisation idempotente du schéma et migrations SQL ;
- diagnostics read-only, healthchecks et résumés de replay ;
- transactions atomiques pour extraction, décodage et matérialisation.
`contracts` ne dépend d’aucun backend. `postgres` implémente ces contrats avec `sqlx`. `lib.rs` ne contient aucune logique métier.
## Responsabilités
## Direction des dépendances
- garantir les invariants des données persistées ;
- séparer contrats et implémentation PostgreSQL à l’intérieur de la crate consolidée ;
- maintenir les tables canoniques `kb_sol_*` ;
- fournir au pipeline des frontières async typées ;
- protéger les opérations multi-tables par transactions ;
- borner toutes les requêtes de diagnostic et de replay exposées.
```text
kb-core
↑
kb-lib ← kb-store
```
## Hors périmètre
`MdCoreInstructionReplayInput` et sa version de contrat appartiennent à `kb-lib`, car ils sont partagés avec les décodeurs. `kb-store` les consomme et les réexporte. `kb-lib` ne dépend jamais de `kb-store`.
La crate ne décode pas les instructions, n’acquiert pas les transactions et ne décide pas quelle matérialisation exécuter. Elle persiste les résultats produits par `kb-lib` et orchestrés par `kb-pipeline`.
`kb-store` ne dépend pas de `kb-config`. L’application résout sa configuration, puis construit explicitement `PostgresStoreOptions`. Cette séparation évite de coupler la persistance à la forme évolutive des profils.
## API publique
## Contrats publics
Les consommateurs utilisent principalement `PostgresStore`, `PostgresStoreOptions`, les traits `*Store`, les DTO `*Insert`/`*Row`, les filtres de replay et les diagnostics. Les constantes de tables et fonctions de validation sont publiques pour les audits et outils d’administration.
Les familles principales sont :
## Relations
- transactions raw et observations d’acquisition ;
- graphe core Solana : transaction, comptes, instructions, inner instructions, logs et balances ;
- sélection et lifecycle de replay ;
- extraction core atomique ;
- décodage, couverture et matérialisation atomiques ;
- ledger de traitement versionné ;
- santé, migrations et pagination bornée.
- dépend de `kb-core` pour les erreurs ;
- utilise les contrats de replay de `kb-lib` ;
- est consommée principalement par `kb-pipeline`, les scénarios de démonstration et le desktop.
Les traits publics sont :
## Statut
- `StoreHealthStore` ;
- `RawTransactionStore` ;
- `CoreTransactionStore` ;
- `CoreExtractionStore` ;
- `DecodePipelineStore` ;
- `ProgramObservationStore` ;
- `DecodedEventStore` ;
- `MaterializedEventStore` ;
- `ProcessingLedgerStore`.
Le stockage consolidé dispose de tests unitaires étendus et de tests PostgreSQL optionnels pilotés par environnement. Les opérations réelles exigent un serveur PostgreSQL et l’application préalable des migrations.
## PostgreSQL
`PostgresStore` fournit :
- connexion depuis `PostgresStoreOptions` validées ;
- création depuis un `sqlx::PgPool` existant ;
- initialisation idempotente des tables raw, core, decode, materialization et ledger ;
- diagnostics de backend, migrations et tables ;
- sélections bornées de candidats de replay ;
- implémentations des traits store-neutral.
Les transactions raw sont immuables. Les écritures core, decode et materialization conservent leur lineage et utilisent le ledger pour le skip version/hash, le force replay et l’idempotence.
Exemple :
```rust
let options = match kb_store::PostgresStoreOptions::new(
database_url,
8,
5_000,
true,
) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let store = match kb_store::PostgresStore::connect(options).await {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return std::result::Result::Ok(store);
```
## Validation
```bash
cargo fmt --all
cargo check -p kb-store
cargo test -p kb-store
cargo clippy -p kb-store --all-targets
KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
cargo test -p kb-store -- --nocapture
```
La validation complète du jalon ajoute :
```bash
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
```
## Documents
- [Utilisation](USAGE.md)
- [Travaux restants](TODO.md)
- [Historique](CHANGELOG.md)
- [Architecture du stockage](../docs/architecture/STORAGE_ARCHITECTURE.md)