0.1.0
This commit is contained in:
147
docs/RAW_STORE.md
Normal file
147
docs/RAW_STORE.md
Normal file
@@ -0,0 +1,147 @@
|
||||
<!-- file: docs/RAW_STORE.md -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Store transactionnel Solana canonique
|
||||
|
||||
## Historique
|
||||
|
||||
`0.2.3` a créé deux tables minimales :
|
||||
|
||||
```text
|
||||
kb_sol_raw_rpc_transactions
|
||||
kb_sol_raw_ws_notifications
|
||||
```
|
||||
|
||||
Ces tables restent un jalon historique validé dans `CHANGELOG.md`. La transition a été appliquée et contrôlée sur PostgreSQL réel pendant `0.3.1`.
|
||||
|
||||
Le modèle actif est :
|
||||
|
||||
```text
|
||||
kb_sol_raw_transactions
|
||||
kb_sol_obs_transaction_observations
|
||||
```
|
||||
|
||||
## Objectif cible
|
||||
|
||||
Le store principal conserve une transaction Solana source-indépendante par signature. Les sources HTTP, WebSocket Helius et Yellowstone gRPC ne doivent pas produire plusieurs copies complètes du même contenu.
|
||||
|
||||
```text
|
||||
source provider
|
||||
-> normalisation canonique
|
||||
-> transaction unique
|
||||
-> observations multiples
|
||||
```
|
||||
|
||||
## Table `kb_sol_raw_transactions`
|
||||
|
||||
Rôle : stocker la représentation canonique rejouable de la transaction et de ses metadata.
|
||||
|
||||
Colonnes principales visées :
|
||||
|
||||
| Colonne | Rôle |
|
||||
|----------------------------|-----------------------------------------|
|
||||
| `id` | clé primaire technique |
|
||||
| `signature` | signature Solana unique |
|
||||
| `slot` | slot de la transaction |
|
||||
| `canonical_format_version` | version du contrat canonique |
|
||||
| `canonical_json` | transaction et metadata normalisées |
|
||||
| `canonical_json_hash` | hash déterministe du document canonique |
|
||||
| `retention_state` | état de rétention |
|
||||
| `processing_state` | état d’extraction et de traitement |
|
||||
| `lifecycle_reason` | raison technique optionnelle |
|
||||
| `created_at` | première insertion |
|
||||
| `updated_at` | dernière évolution autorisée |
|
||||
|
||||
Le contenu canonique ne contient pas de nom de fournisseur, endpoint, subscription id ou format de transport.
|
||||
|
||||
`kb_model::CanonicalTransaction` fournit la sérialisation déterministe et le hash SHA-256. `kb_store_core::RawTransactionInsert::from_canonical` construit le DTO de persistance avec la signature primaire, le slot, `canonical_format_version`, `canonical_json` et `canonical_json_hash`. Le transport RPC ne dépend donc pas du backend PostgreSQL.
|
||||
|
||||
## Table `kb_sol_obs_transaction_observations`
|
||||
|
||||
Rôle : enregistrer chaque détection ou acquisition d’une signature sans recopier le payload complet.
|
||||
|
||||
Colonnes principales visées :
|
||||
|
||||
| Colonne | Rôle |
|
||||
|-----------------------|-------------------------------------------------------|
|
||||
| `id` | clé primaire technique |
|
||||
| `observation_key` | clé idempotente de l’observation |
|
||||
| `raw_transaction_id` | lien optionnel vers `kb_sol_raw_transactions` |
|
||||
| `signature` | signature détectée ou reçue |
|
||||
| `slot` | slot quand connu |
|
||||
| `provider` | fournisseur |
|
||||
| `endpoint_code` | endpoint de configuration |
|
||||
| `protocol` | protocole de transport |
|
||||
| `acquisition_method` | méthode ou type de stream |
|
||||
| `origin` | `live`, `backfill`, `replay`, `repair` ou `migration` |
|
||||
| `commitment` | commitment demandé ou reçu |
|
||||
| `capture_session_id` | session de mesure ou d’ingestion |
|
||||
| `filter_code` | filtre logique utilisé |
|
||||
| `detected_at` | premier signal reçu |
|
||||
| `received_at` | transaction complète reçue |
|
||||
| `normalized_at` | fin de normalisation |
|
||||
| `persisted_at` | fin de persistance |
|
||||
| `payload_size_bytes` | taille du message source |
|
||||
| `source_payload_hash` | hash optionnel du message source |
|
||||
| `status` | résultat technique |
|
||||
| `error_code` | erreur normalisée optionnelle |
|
||||
| `error_message` | message de diagnostic optionnel |
|
||||
|
||||
Cette table ne possède pas de `raw_json`, de `canonical_json` ni de payload Protobuf complet.
|
||||
|
||||
## Notifications WebSocket
|
||||
|
||||
`kb_sol_raw_ws_notifications` n’est plus conservée comme cible durable.
|
||||
|
||||
Pour `logsSubscribe` :
|
||||
|
||||
1. recevoir la signature et le slot ;
|
||||
2. mémoriser temporairement le timestamp de détection ;
|
||||
3. hydrater par `getTransaction` si nécessaire ;
|
||||
4. écrire la transaction canonique ;
|
||||
5. écrire une observation avec `detected_at`, `received_at` et le statut d’hydratation.
|
||||
|
||||
Les payloads complets de notifications peuvent être exportés temporairement pour un benchmark borné, mais ils ne doivent pas être dupliqués en PostgreSQL.
|
||||
|
||||
## Fusion par signature
|
||||
|
||||
La signature est la clé d’unicité de la transaction canonique.
|
||||
|
||||
- hash identique : conserver la ligne et ajouter une observation ;
|
||||
- metadata plus complètes : appliquer un enrichissement déterministe ;
|
||||
- différence incompatible : enregistrer un conflit et ne pas écraser silencieusement ;
|
||||
- transaction absente ou erreur provider : écrire uniquement l’observation technique.
|
||||
|
||||
## Cycle de vie
|
||||
|
||||
Les états de rétention de la transaction canonique restent :
|
||||
|
||||
```text
|
||||
full
|
||||
compacted
|
||||
archived
|
||||
purged
|
||||
```
|
||||
|
||||
Les états de traitement restent :
|
||||
|
||||
```text
|
||||
received
|
||||
core_extracted
|
||||
decoded
|
||||
materialized
|
||||
failed
|
||||
```
|
||||
|
||||
Les observations sont append-only et suivent une rétention technique distincte.
|
||||
|
||||
## Baseline SQL active
|
||||
|
||||
Après validation de la transition historique, le dossier `kb_store_pg/migrations/` a été consolidé :
|
||||
|
||||
```text
|
||||
0001_canonical_transaction_store.sql
|
||||
0002_core_store.sql
|
||||
```
|
||||
|
||||
La baseline ne contient que les tables et colonnes actives. Les anciens noms RPC/WS ne sont plus recréés. Le DDL runtime conserve temporairement un chemin de compatibilité idempotent pour les workspaces encore issus de `pre.001`.
|
||||
Reference in New Issue
Block a user