74 lines
3.0 KiB
Markdown
74 lines
3.0 KiB
Markdown
<!-- file: docs/CORE_STORE.md -->
|
||
<!-- version: 3 -->
|
||
|
||
# Store core Solana
|
||
|
||
## Évolution `0.3.4`
|
||
|
||
Le store core historique devient alimenté par un extracteur transactionnel à partir de `kb_sol_raw_transactions.canonical_json`.
|
||
|
||
| Table | Rôle |
|
||
|----------------------------------|------------------------------------------------------------|
|
||
| `kb_sol_core_transactions` | Transaction normalisée, statut et lien vers la ligne raw. |
|
||
| `kb_sol_core_account_keys` | Espace résolu statique + ALT avec flags Solana. |
|
||
| `kb_sol_core_instructions` | Instructions top-level et payload canonique hashé. |
|
||
| `kb_sol_core_inner_instructions` | Inner instructions rattachées à un chemin parent. |
|
||
| `kb_sol_core_logs` | Logs ordonnés, texte hashé et lien d’invocation optionnel. |
|
||
| `kb_sol_core_balance_changes` | Deltas natifs, SPL Token et Token-2022. |
|
||
| `kb_sol_ops_processing_ledger` | Version, hash, statut et tentatives du processor. |
|
||
|
||
## Écriture atomique
|
||
|
||
Une extraction réussie exécute dans la même transaction PostgreSQL :
|
||
|
||
1. validation du bundle ;
|
||
2. recherche d’un graphe core existant ;
|
||
3. suppression en cascade de ce graphe pour la signature ;
|
||
4. insertion de la transaction et de toutes ses lignes filles ;
|
||
5. passage de la ligne raw à `core_extracted` ;
|
||
6. upsert du ledger en `succeeded` ;
|
||
7. commit.
|
||
|
||
Une erreur déclenche le rollback implicite de la transaction. L’enregistrement terminal d’un échec utilise une transaction dédiée et marque la ligne raw `failed` avec un diagnostic rejouable.
|
||
|
||
## Clés d’idempotence
|
||
|
||
Les contraintes actives restent :
|
||
|
||
```text
|
||
core transaction : signature
|
||
account key : signature + account_index
|
||
instruction top-level : signature + instruction_path
|
||
inner instruction : signature + instruction_path
|
||
log : signature + log_index
|
||
balance change : signature + balance_change_index
|
||
ledger : stage + processor_name + processor_version + input_key
|
||
```
|
||
|
||
Le ledger ajoute `input_hash` à la décision de skip sans l’ajouter à la clé unique. Un nouvel hash met à jour la même identité de processor et augmente `attempt_count`.
|
||
|
||
## Sélection raw
|
||
|
||
Le contrat `CoreExtractionSelectionFilter` permet :
|
||
|
||
- une liste de signatures ;
|
||
- une plage inclusive de slots ;
|
||
- un état raw ;
|
||
- un program id déjà indexé dans les instructions core ;
|
||
- une limite stricte.
|
||
|
||
Le filtre par program id est un mode de replay. Il ne peut pas découvrir un programme dans une transaction qui n’a jamais encore été extraite.
|
||
|
||
## Repositories
|
||
|
||
`CoreExtractionStore` isole le pipeline du backend :
|
||
|
||
```text
|
||
list_raw_transactions_for_core_extraction
|
||
is_core_extraction_current
|
||
persist_core_extraction
|
||
mark_core_extraction_failed
|
||
```
|
||
|
||
Les repositories historiques d’insertion unitaire restent disponibles, mais le worker `0.3.4` utilise exclusivement l’écriture atomique du bundle.
|