116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
<!-- file: docs/RAW_STORAGE_LIFECYCLE.md -->
|
||
<!-- version: 4 -->
|
||
|
||
# Cycle de vie du stockage transactionnel Solana
|
||
|
||
## Principe général
|
||
|
||
Le stockage rejouable repose désormais sur une transaction Solana canonique unique par signature. Les formats d’origine JSON-RPC, WebSocket Helius ou Yellowstone Protobuf sont des formats de transport, pas des modèles de stockage métier.
|
||
|
||
Le cycle est :
|
||
|
||
```text
|
||
acquisition
|
||
-> normalisation canonique
|
||
-> persistance raw canonique
|
||
-> extraction core
|
||
-> décodage
|
||
-> matérialisation
|
||
-> compaction / archivage / purge éventuelle
|
||
```
|
||
|
||
## Transaction canonique
|
||
|
||
`kb_sol_raw_transactions` conserve suffisamment d’information pour :
|
||
|
||
- auditer une transaction ;
|
||
- reconstruire les tables `core` ;
|
||
- rejouer de nouvelles versions de décodeurs ;
|
||
- rejouer de nouvelles versions de matérialiseurs ;
|
||
- comparer plusieurs sources sans dépendre de leur format.
|
||
|
||
La ligne est unique par signature. `canonical_format_version` permet de faire évoluer le contrat sans ambiguïté.
|
||
|
||
## Observations d’acquisition
|
||
|
||
`kb_sol_obs_transaction_observations` conserve les preuves techniques d’acquisition :
|
||
|
||
- fournisseur et endpoint ;
|
||
- protocole et méthode ;
|
||
- origine live/backfill/replay/réparation ;
|
||
- commitment ;
|
||
- session et filtre ;
|
||
- timestamps de détection, réception, normalisation et persistance ;
|
||
- taille du message ;
|
||
- statut et erreur éventuelle.
|
||
|
||
Cette table ne conserve pas le payload complet. Elle peut contenir plusieurs lignes pour une même signature.
|
||
|
||
## Ancienne table WebSocket
|
||
|
||
`kb_sol_raw_ws_notifications` est une table historique de `0.2.3`, supprimée pendant la transition validée `0.3.1`. Elle n’existe plus dans la baseline SQL active.
|
||
|
||
Les nouvelles notifications WebSocket ne doivent pas être stockées intégralement par défaut. Une notification de logs peut rester temporairement dans une queue mémoire jusqu’à l’hydratation de la transaction.
|
||
|
||
## États de rétention
|
||
|
||
Les états de rétention de `kb_sol_raw_transactions` sont :
|
||
|
||
```text
|
||
full
|
||
compacted
|
||
archived
|
||
purged
|
||
```
|
||
|
||
### `full`
|
||
|
||
Le document canonique complet est présent dans PostgreSQL.
|
||
|
||
### `compacted`
|
||
|
||
Une représentation réduite ou un stockage externe permet encore l’audit minimal, mais le payload canonique complet n’est plus dans la ligne chaude.
|
||
|
||
### `archived`
|
||
|
||
Le payload a été déplacé vers un stockage d’archive durable.
|
||
|
||
### `purged`
|
||
|
||
Le payload n’est plus disponible. Le hash canonique, la signature, le slot et les données dérivées doivent rester suffisants pour les diagnostics autorisés.
|
||
|
||
## États de traitement
|
||
|
||
```text
|
||
received
|
||
core_extracted
|
||
decoded
|
||
materialized
|
||
failed
|
||
```
|
||
|
||
L’état décrit la progression de la transaction canonique, pas celle de chaque observation de source.
|
||
|
||
## Conditions avant compaction ou purge
|
||
|
||
Aucune purge destructive ne doit être activée avant validation de :
|
||
|
||
- l’extraction core idempotente ;
|
||
- la couverture des décodeurs prioritaires ;
|
||
- la reconstruction depuis archive ;
|
||
- la stabilité du hash canonique ;
|
||
- la conservation du ledger de traitement ;
|
||
- la stratégie de sauvegarde PostgreSQL.
|
||
|
||
## Payloads fournisseur de diagnostic
|
||
|
||
Les payloads complets spécifiques à un fournisseur peuvent être exportés temporairement pour une session de test. Ils ne doivent pas devenir une dépendance du replay métier.
|
||
|
||
Un export de diagnostic doit être :
|
||
|
||
- opt-in ;
|
||
- borné en durée et en taille ;
|
||
- associé à une session ;
|
||
- supprimable indépendamment de PostgreSQL.
|
||
|